forked from jgrewe/fishbook
[docs] more more more
This commit is contained in:
parent
472f771cb5
commit
32f4f23527
@ -1,118 +1,39 @@
|
||||
# How to use the fishbook
|
||||
|
||||
## Requirements
|
||||
## Requirements & Installation
|
||||
|
||||
* Python 3.5+ only, **no** python 2
|
||||
* [datajoint](https://datajoint.io) to connect to the database and to map python objects to table entries.
|
||||
* [nixio](https://github.com/g-node/nixpy) to read the relacs-flavored nix files during import or later during data retrieval.
|
||||
|
||||
## Installation
|
||||
|
||||
### 1) Clone the repository
|
||||
### Clone the repository
|
||||
|
||||
```bash
|
||||
```shell
|
||||
>> git clone https://whale.am28.uni-tuebingen.de/git/jgrewe/fishbook.git
|
||||
```
|
||||
|
||||
### 2) Installation
|
||||
### Install
|
||||
|
||||
When installing for development: install for the current user, install as "editable":
|
||||
|
||||
```bash
|
||||
```shell
|
||||
>> cd fishbook
|
||||
>> pip3 install -e fishbook --user
|
||||
```
|
||||
|
||||
When installing for use:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
>> pip3 install fishbook --user
|
||||
# or, for system-wide installation
|
||||
>> sudo pip3 install fishbook
|
||||
```
|
||||
|
||||
### Running *fishbook*
|
||||
|
||||
### 3) Installing a local database server
|
||||
To run fishbook you need access to a database server. If you have access to one proceed with [configuring](configuration.md) the project. Otherwise, if you want to run it using a local database server see [these instructions](setting_up.md).
|
||||
|
||||
When you want to run *fishbook* locally you need to install a local database server (either mariaDB or mysql).
|
||||
|
||||
On Ubuntu or Linux mint use *apt* to install the server
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install mariadb-server
|
||||
sudo mysql_secure_installation
|
||||
```
|
||||
|
||||
On Fedora use *dnf*
|
||||
|
||||
```bash
|
||||
sudo dnf update
|
||||
sudo dnf install mariadb-server
|
||||
sudo mysql_secure_installation
|
||||
```
|
||||
|
||||
On MacOS the most convenient way is to use [*homebrew*](https://brew.sh) see also [mariadb documentation](https://mariadb.com/kb/en/installing-mariadb-on-macos-using-homebrew/)
|
||||
|
||||
```bash
|
||||
brew install mariadb
|
||||
mysql.server start
|
||||
brew services start mariadb # to automatically start the server upon boot
|
||||
```
|
||||
|
||||
On Windows you probably need to download an installer...
|
||||
|
||||
Upon installation you should be able to log into the database as root without a password.
|
||||
|
||||
```bash
|
||||
mysql -u root
|
||||
```
|
||||
|
||||
To allow *datajoint* to store stuff on the server you need to:
|
||||
1. Create a database on the server.
|
||||
2. Add a user and grant this user read and write access.
|
||||
|
||||
### Creating a database
|
||||
|
||||
At the moment *fishbook* assumes that your database is called **fish_book**. To create it log into the server
|
||||
|
||||
```bash
|
||||
mysql -u root -p
|
||||
```python
|
||||
import fishbook as fb
|
||||
```
|
||||
|
||||
And and execute the following commands
|
||||
|
||||
```sql
|
||||
MariaDB [(none)]> CREATE DATABASE fish_book CHARACTER SET = utf8;
|
||||
MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'localhost' IDENTIFIED BY 'password';
|
||||
MariaDB [(none)]> FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
The first command creates the empty database and sets the Character set to utf8. This is important at least when it comes to *fishbook*. The second row creates a user **foo** and grants that user all rights on all tables of **fish_book**. So far **foo** can only log in from the local machine. In order to grant access also from outsides you need to issue a second command:
|
||||
|
||||
```sql
|
||||
MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'%' IDENTIFIED BY 'password';
|
||||
MariaDB [(none)]> FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
From localhost you should now be able to log into the **fish_book** database by
|
||||
|
||||
```bash
|
||||
mysql fish_book -u foo -p
|
||||
```
|
||||
|
||||
From outsides use
|
||||
|
||||
```shell
|
||||
mysql fish_book -h yourhost.yourdomain -u foo -p
|
||||
```
|
||||
|
||||
### Things to remember
|
||||
|
||||
* Database engine must be InnoDB, which is default in MariaDB
|
||||
* **OperationalError: (1071, 'Specified key was too long; max key length is 3072 bytes')**
|
||||
Caused by a wrong character set check that it is set to utf8:
|
||||
```sql
|
||||
ALTER DATABASE `fish_book` CHARACTER SET utf8;
|
||||
```
|
||||
|
||||
|
||||
83
docs/setting_up.md
Normal file
83
docs/setting_up.md
Normal file
@ -0,0 +1,83 @@
|
||||
# Installing a local database server
|
||||
|
||||
When you want to run *fishbook* locally you need to install a local database server (either mariaDB or mysql).
|
||||
|
||||
On Ubuntu or Linux mint use *apt* to install the server
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install mariadb-server
|
||||
sudo mysql_secure_installation
|
||||
```
|
||||
|
||||
On Fedora use *dnf*
|
||||
|
||||
```bash
|
||||
sudo dnf update
|
||||
sudo dnf install mariadb-server
|
||||
sudo mysql_secure_installation
|
||||
```
|
||||
|
||||
On MacOS the most convenient way is to use [*homebrew*](https://brew.sh) see also [mariadb documentation](https://mariadb.com/kb/en/installing-mariadb-on-macos-using-homebrew/)
|
||||
|
||||
```bash
|
||||
brew install mariadb
|
||||
mysql.server start
|
||||
brew services start mariadb # to automatically start the server upon boot
|
||||
```
|
||||
|
||||
On Windows you probably need to download an installer...
|
||||
|
||||
Upon installation you should be able to log into the database as root without a password.
|
||||
|
||||
```bash
|
||||
mysql -u root
|
||||
```
|
||||
|
||||
To allow *datajoint* to store stuff on the server you need to:
|
||||
1. Create a database on the server.
|
||||
2. Add a user and grant this user read and write access.
|
||||
|
||||
## Creating a database
|
||||
|
||||
At the moment *fishbook* assumes that your database is called **fish_book**. To create it log into the server
|
||||
|
||||
```bash
|
||||
mysql -u root -p
|
||||
```
|
||||
|
||||
And and execute the following commands
|
||||
|
||||
```sql
|
||||
MariaDB [(none)]> CREATE DATABASE fish_book CHARACTER SET = utf8;
|
||||
MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'localhost' IDENTIFIED BY 'password';
|
||||
MariaDB [(none)]> FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
The first command creates the empty database and sets the Character set to utf8. This is important at least when it comes to *fishbook*. The second row creates a user **foo** and grants that user all rights on all tables of **fish_book**. So far **foo** can only log in from the local machine. In order to grant access also from outsides you need to issue a second command:
|
||||
|
||||
```sql
|
||||
MariaDB [(none)]> GRANT ALL ON fish_book.* TO 'foo'@'%' IDENTIFIED BY 'password';
|
||||
MariaDB [(none)]> FLUSH PRIVILEGES;
|
||||
```
|
||||
|
||||
From localhost you should now be able to log into the **fish_book** database by
|
||||
|
||||
```bash
|
||||
mysql fish_book -u foo -p
|
||||
```
|
||||
|
||||
From outsides use
|
||||
|
||||
```shell
|
||||
mysql fish_book -h yourhost.yourdomain -u foo -p
|
||||
```
|
||||
|
||||
## Things to remember
|
||||
|
||||
* Database engine must be InnoDB, which is default in MariaDB
|
||||
* **OperationalError: (1071, 'Specified key was too long; max key length is 3072 bytes')**
|
||||
Caused by a wrong character set check that it is set to utf8:
|
||||
```sql
|
||||
ALTER DATABASE `fish_book` CHARACTER SET utf8;
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user