Installing Seshat¶
We’ve made the installation of Seshat as simple as possible.
- If you don’t have access to a Linux server or have very sparse knowledge of how to set up a web server and configure it, you should follow the Docker Install (Easy way) procedure. This also goes for more seasoned linux users that don’t want to go through the hassle of setting up each parts of the server and client manually.
- If you like to have a finer control of your system and/or don’t want to deal with Docker, follow the Manual Install
These two tutorial will help you Seshat on your machine, it will thus be only accessible to your or users on your local network. If you want Seshat to be reachable from the web, follow Setting up Seshat to be accessible from the web after installing.
Docker Install (Easy way)¶
This type of install should work on any machine, regardless of the OS (Windows, Mac, Linux, although Unix systems are prefered), as long as you have the following requirements:
A working install of Docker (we know it works with Docker 19.03 and later, it might work with earlier versions). If you don’t have Docker installed:
On MacOS or Windows, follow the install instructions for “Desktop”.
On Linux follow the install instructions for “Sever” (pick the right distibution). Pick the Community Edition (CE) install.
After installing, you should make sure your current user has the right to run Docker images (by running
docker run hello-word
for instance). If that isn’t the case, follow these instructions.
If you installed docker on Linux (namely, Ubuntu) make sure that you have docker-compose installed as well.
You should also also have Git installed on your system, to retrieve Seshat’s sources. If you don’t, follow these intructions.
Once all these prerequisites are all installed, open a terminal, and retrieve the full Seshat sources
git clone --recurse-submodules git@github.com:bootphon/seshat.git
Then, change the current directory to seshat’s previously cloned directory
cd seshat/
Once you’re in that folder, edit (using any text editor) the docker-compose.yml
file
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | version: "3" services: mongo: image: mongo:latest tty: true stdin_open: true container_name: seshat_mongo_db ports: - "127.0.0.1:27017:27017" volumes: - ./mongodata:/data/db restart: always server: build: . image: 'seshat/server:prod' container_name: seshat ports: - "5000:80" - "4200:4200" restart: always depends_on: - mongo volumes: # set the corpora folder mounting point. You can set it to something different. For instance, if you # corpora folder is /home/mark/data/my_corpora, this line will be # - /home/mark/data/my_corpora:/app/corpora # DO NOT change the second part of this line (the ":/app/corpora") # DO NOT add another mounting point other than this one for the corpora folder - ./corpora:/app/corpora environment: - FLASK_CONFIG=docker - ADMIN_USERNAME=manager_username - ADMIN_PASSWORD="your_admin_password" - ADMIN_EMAIL="test@test.com" - ADMIN_FIRST_NAME="Perceval" - ADMIN_LAST_NAME="Le Gaulois" |
Edit all the parameters defining the first admin’s accounts properties:
- For the username
ADMIN_USERNAME
use alphanumerical characters, no spaces - The password
ADMIN_PASSWORD
should be at least 8 characters long - The email defined in
ADMIN_EMAIL
should be a valid email address. If you don’t want to put any, just leave the default one. - Regarding the
FIRST_NAME
andLAST_NAME
variables, any string will do
Note
It’s important that you set your password to something secure. Do not ignore this step and leave the example password preset.
Now, copy one or more of your corpus’s folder to the corpora/
folder that is already present. Do it either using
your OS’s file browser, or by running the following command
cp -r /path/to/your/corpus/folder corpora/
Once that is done, still in the seshat/
folder, tell docker to build and run your local image.
The build part might take some time.
docker-compose build
docker-compose up
This will automatically download the required Docker images, install them and setup Seshat and its database in a Docker environment. Once you see the message the following messages displayed in your terminal, it means it’s finished.
Test your access to the now active application by reaching the address http://localhost:4200 in your browser.
Check that you can log in with the username and password you specified in the configuration file.
You can now add audio corpora to Seshat, so you can start your first annotation campaign.
Check that your corpora is in line with Seshat Audio Corpus Management, and just drop it in the corpora
folder (still in Seshat’s current folder), or any other corpora folder that you set up during the configuration.
Once that is done, you can start using Seshat, or learn how to use it in the Campaign Creation Tutorial.
Note
You can cut the running docker images with Ctrl-C. If you want them to run in the background,
run docker-compose up -d
(the -d
stands for daemon).
Manual Install¶
This type of install is advised if you’re good enough as a Linux system administrator, and don’t want to have to deal with Docker. It’s considerably easier to tweak and customize the install with this kind of installation.
This install is for an Ubuntu 18.04 environment (it could potentially work on other environments distributions or MacOS but has not been thoroughly tested). We here assume that your system has the following requirements:
- A working python 3.6>= (default Python version on Ubuntu 18.04)
- A working nodeJS 12.3>= install
- A mongoDB 3.6>= install (it could work with earlier versions)
- An ffmpeg install
Moreover, the advised web server to act as a web frontend is Nginx.
Preliminaries¶
First of all, clone the full seshat project and cd
into it
git clone --recurse-submodules git@github.com:bootphon/seshat.git
cd seshat/
Setting up the API (server)¶
First, cd
into the server’s directory, set up a python virtual environment, and install the seshat package:
cd server/
python3 -m venv venv/
. venv/bin/activate
python setup.py install
You should be able to run the server now, by running:
python app.py
Check that it is running by reaching the address http://localhost:5000/doc/swagger. You should see a page displaying a description of Seshat’s RESTful API.
Setting up the client¶
Now go to the client’s directory (assuming you’re still in the server’s directory). Then, install the npm dependencies and compile the client’s Angular Typescript code into JavaScript:
cd ../client/
npm install
npm run build -- --prod true --outputPath=../server/static/
Now go back to the server’s directory, and run python app.py
again. If you reach the address
http://localhost:5000/, your should get Seshat’s login page.
Creating a manager’s account¶
Still in the server’s virtual environment, run the command (whilst replacing the example values with your own)
add-manager manager_username manager_password manager@email.com --first_name Manager --last_name Mister
If you go back to the http://localhost:5000/ page, you should now be able to login with the supplied username and password. At this point, your installation of Seshat is fully usable, albeit not very practical.
You can drop corpus files in the default server/corpora/
folder for Seshat to use for annotation. Be sure to
comply with the Seshat Audio Corpus Management.
Having Seshat as a Daemon¶
Having to launch Seshat by hand each time you use it isn’t very practical. If you’re willing to have Seshat an automatic launch of Seshat when your machine (or server) boots, follow these steps to have Seshat “daemonized” using SystemD. Note that if you wish to have seshat served by nginx, it’s one of the required steps, thus, this isn’t wasted time in any way.
First, make sure you have no already running instance of Seshat (as it will conflict with the deamonized one if their ports are the same).
Edit the seshat.service
found in the install/
folder of the clone repository, configuring it with your
own paths and your own username:
1 2 3 4 5 6 7 8 9 10 11 12 13 | [Unit] Description=uWSGI instance serving the seshat website After=network.target [Service] User=your_user Group=www-data WorkingDirectory=/path/to/seshat/server/ Environment="PATH=/path/to/seshat/server/venv/bin:/usr/bin" ExecStart=/path/to/seshat/server/venv/bin/uwsgi --ini wsgi/seshat_http.ini [Install] WantedBy=multi-user.target |
Then, copy that file to systemd’s services directory, and start the deamon:
sudo cp install/seshat.service /etc/systemd/system/seshat.service
sudo systemctl start seshat.service
sudo systemctl status seshat.service
The last command should say that seshat’s service is active. Seshat should now be running on the same address as usual, http://localhost:5000/.
If you wish to have Seshat running on boot, run:
sudo systemctl enable seshat.service
If you wish to serve Seshat to the web, proceed to Setting up Seshat to be accessible from the web .