Commit 3bcda40e authored by Mathieu Giraud's avatar Mathieu Giraud
Browse files

doc/server.md: détails, réorganisation

parent 21c458ac
Pipeline #42673 failed with stages
in 47 seconds
......@@ -99,23 +99,14 @@ However, the following network access are recommended:
provided a SSH access can be arranged, possibly over VPN.
# Docker installation
# Docker -- Installation
All our images are hosted on DockerHub and can be retrieved from the
repository [vidjil/vidjil](https://hub.docker.com/r/vidjil/vidjil/).
Our docker environment makes use of docker-compose (<https://docs.docker.com/compose/>).
All Vidjil components
are currently packaged into a single docker image. Individual services are
started by docker-compose, such as in this [example](http://gitlab.vidjil.org/blob/master/docker/docker-compose.yml).
The last image is tagged with `vidjil/vidjil:latest`.
All Vidjil components are currently packaged into a single docker image.
Individual services are started by docker-compose (<https://docs.docker.com/compose/>).
## Versions
- 1.1
- 1.2
- 1.3
- 1.3.1
- 1.3.2
- 1.4.2
## Before installation
......@@ -124,61 +115,29 @@ Install `docker-compose`. See <https://docs.docker.com/compose/install/#install-
If it doesn't exist yet, you should create a `docker` group.
The users needing to access `docker` must belong to this group.
Retrieve the git XXXX available at XXXX.
Directory `docker`.
This contains both `docker-compose.yml` as well as
Install `git`.
Clone the [Vidjil git](https://gitlab.inria.fr/vidjil/vidjil) with `git clone https://gitlab.inria.fr/vidjil/vidjil.git`,
and go to the directory [vidjil/docker](https://gitlab.inria.fr/vidjil/vidjil/tree/dev/docker).
This contains both [docker-compose.yml](http://gitlab.vidjil.org/blob/dev/docker/docker-compose.yml) as well as configuration files.
## Docker environment
The vidjil Docker environment is managed by docker-compose since it is
composed of several different services this allows us to easily start and
stop individual services.
The vidjil Docker environment is managed by `docker-compose`, who launches the following services:
The services managed by docker-compose are as follows:
- `mysql` The database
- `uwsgi` The Web2py backend server
- `nginx` The web server, containing the client web application
- `workers` The Web2py Scheduler workers in charge of executing vidjil users' samples
- mysql The database
- uwsgi The Web2py backend server
- fuse The XmlRPCServer that handles custom fuses (for comparing
samples)
- nginx The web server, containing the client web application
- workers The Web2py Scheduler workers in charge of executing vidjil
users' samples
- backup Starts a cron job to schedule regular backups
- reporter A monitoring utility that can be configured to send
monitoring information to a remote server
- `fuse` The XmlRPCServer that handles queries for comparing samples
- `backup` Starts a cron job to schedule regular backups
- `reporter` A monitoring utility that can be configured to send monitoring information to a remote server
Backup and reporter services can be commented out.
## Configuring the Vidjil container for a network usage
The container may be further configured to make it available to a whole network.
The following configuration files are found in the vidjil directory:
- `conf/conf.js` various variables for the vidjil browser
- `conf/defs.py` various variables for the vidjil server
- `conf/gzip.conf` configuration for gzip in nginx
- `conf/gzip_static`.conf same as the previous but for static resources
- `conf/uwsgi.ini` configuration required to run vidjil with uwsgi
- `sites/nginx` configuration required when running vidjil with nginx
- `scripts/nginx-entrypoint.sh` entrypoint for the nginx
- `service` (not currently in use)
- `scripts/uwsgi-entrypoint.sh` entrypoint for the uwsgi
service. Ensures the owner of some relevant volumes are correct within
the container and starts uwsgi
Here are some notable configuration changes you should consider:
Go to `vidjil/docker
### Passwords
- Change the mysql root password in `docker-compose.yml`
- Change the mysql vidjil password in `mysql/create_db.sql` and sets it also in `vidjil-server/conf/defs.py`
### Hostname
If you plan to use Vidjil only locally, these steps are not required.
If you plan to use Vidjil only locally, these steps are not required.
- Change the hostname in the nginx configuration `vidjil-client/conf/nginx_web2py`,
replacing `$hostname` with your FQDN.
......@@ -186,73 +145,94 @@ Go to `vidjil/docker
change all 'localhost' to the FQDN
- Configure the SSL certificates
- one option is to create a self-signed SSL certificate:
- A fast option is to create a self-signed SSL certificate.
Note that it will trigger security warnings when accessing the client.
```
openssl genrsa 4096 > web2py.key
openssl req -new -x509 -nodes -sha1 -days 1780 -key web2py.key > web2py.crt
openssl x509 -noout -fingerprint -text < web2py.crt
mv web2py.* docker/vidjil-client/ssl/
```
It will trigger warnings
- a better option is to configure letsencrypt
In `docker-compose.yml`, update `nginx.volumes` to add the directory where
the certificate is located.
- A better option is to use other certificates, for example by configuring free [Let's Encrypt](https://letsencrypt.org/) certificates;
In `docker-compose.yml`, update `nginx.volumes` to add the directory with the certifictes.
## First launch
- Comment backup/reporter services !!!
It is avised to first launch `docker-compose up mysql`. The first time,
this container create the database and it takes some time.
Launch docker-compose `docker-compose up`
## First configuration and first launch
- Change the mysql root password in `docker-compose.yml`
- Change the mysql vidjil password in `mysql/create_db.sql` and sets it also in `vidjil-server/conf/defs.py`
- Comment backup/reporter services in `docker-compose.yml`
`docker ps` should display four running containers:
docker_nginx_1, docker_uwsgi_1, docker_fuse_1, docker_mysql_1
- It is avised to first launch with `docker-compose up mysql`.
The first time, this container create the database and it takes some time.
- When `mysql` is launched,
you can safely launch `docker-compose up`.
Then `docker ps` should display four running containers:
`docker_nginx_1`, `docker_uwsgi_1`, `docker_fuse_1`, `docker_mysql_1`
- `make germline` to create `germline/`. You should accept IMGT licences. XXXX
- Copy the germline.js `docker cp browser/js/germline.js docker_nginx_1:/usr/share/vidjil/browser/js/germline.js`
`docker commit docker_nginx_1 vidjil/client:latest`
- From the `vidjil` directory, run `make germline` to create `germline/`. You should accept IMGT licences.
- Copy the `germline.js` with `docker cp browser/js/germline.js docker_nginx_1:/usr/share/vidjil/browser/js/germline.js`
and `docker commit docker_nginx_1 vidjil/client:latest`
Open a web browser to <https://your-hostname>
- Open a web browser to <https://your-hostname>.
Create a first account by entering an email.
This account is the main root account of the server. Other administrators could then be created.
It will be also used for the web2py admin passwor.
## Further configuration
### Further configuration
The following configuration files are found in the `vidjil/docker` directory:
- `conf/conf.js` various variables for the vidjil browser
- `conf/defs.py` various variables for the vidjil server
- `conf/gzip.conf` configuration for gzip in nginx
- `conf/gzip_static`.conf same as the previous but for static resources
- `conf/uwsgi.ini` configuration required to run vidjil with uwsgi
- `sites/nginx` configuration required when running vidjil with nginx
- `scripts/nginx-entrypoint.sh` entrypoint for the nginx
- `service` (not currently in use)
- `scripts/uwsgi-entrypoint.sh` entrypoint for the uwsgi
service. Ensures the owner of some relevant volumes are correct within
the container and starts uwsgi
Here are some notable configuration changes you should consider:
- mysql root password (`mysql.environment` in `docker-compose.yml`), mysql vidjil password (`docker-compose.yml` and `vidjil-server/conf/defs.py`),
as mentionned above
- Change the `FROM_EMAIL` and `ADMIN_EMAILS` variables in `vidjil-server/conf/defs.py`. These
represent the sender email address and the destination email addresses,
used in reporting patient milestones and server errors.
- Change the volumes in `docker-compose.yml`. By default all files that
- Change the `volumes` in `docker-compose.yml`. By default all files that
require saving outside of the containers (the database, uploads, vidjil
results and log files) are stored in `/opt/vidjil`, but you can change
this by editing the paths in the volumes.
XXX Size, XXXXX
See also <a href="#storage">Requirements / Storage</a> above.
- Configure the reporter. Ideally this container should be positioned
on a remote server in order to be able to report on a down server, but we have packed it here for convenience.
You will also
need to change the `DB_ADDRESS` in `conf/defs.py` to match it.
### Starting the environment
### XXX ? XXX
Ensure your `docker-compose.yml` contains the correct reference to the
vidjil image you want to use. Usually this will be `vidjil/vidjil:latest`,
but more tags are available at <https://hub.docker.com/r/vidjil/vidjil/tags/>.
XXXX ? XXXX
You may also want to uncomment the volume in the fuse volume block
`./vidjil/conf:/etc/vidjil`.
This will provide easier access to all of the
......@@ -260,33 +240,20 @@ configuration files, allowing for tweaks.
From this location, it will be easier to enable more software or pipelines
by putting their binaries in this location taht will be see by the docker instance.
Running the following command will automatically download any missing
images and start the environment:
``` bash
docker-compose up
```
If you are using the backup and reporter images, then you need to first
build these from the image you are using by running the following:
``` bash
docker-compose up --build
```
# Docker -- Troubleshooting
This will also start the environment for you.
### Troubleshooting
Errors "Can't connect to MySQL server on 'mysql'"
### Error "Can't connect to MySQL server on 'mysql'"
The mysql container is not fully launched. This can happen especially at the first launch.
Relaunch the containers.
XXXX Relaunch the workers.
### Updating a Docker installation
# Docker -- Updating a Docker installation
**(October 2018: Temporary instructions, please wait.)**
By security, we please you to make a backup before doing this process.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment