From 537fc41514c1f498a46e15976fadf93577e52379 Mon Sep 17 00:00:00 2001 From: Sylvain Date: Thu, 14 Dec 2017 14:33:49 +0100 Subject: [PATCH] [doc] docker installation instructions --- CHANGELOG.md | 1 + docker/README.md | 122 +++++++++++++++++++++++++---------------------- 2 files changed, 65 insertions(+), 58 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 07ad0a815..23e47bb5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ - Fix a bug: refund an invoice with a subscription and disabling it a the same time cause the resulting PDF to display the wrong dates - Fix a security issue: in development environments, web-console has a vulnerability as described in CVE-2015-3224 - Fixed deploy instructions with docker-compose +- Updated docker installation instructions ## v2.6.0 2017 November 13 diff --git a/docker/README.md b/docker/README.md index 1b0bfe745..0599a94f5 100644 --- a/docker/README.md +++ b/docker/README.md @@ -13,26 +13,28 @@ You will need to be root through the rest of the setup. 1.2. Setup the domain name
1.3. Connect through SSH
1.4. Prepare the server
-1.5. Setup folders and env file
-1.6. setup nginx file
-1.7. SSL certificate with LetsEncrypt
-1.8. requirements +1.5. Retrieve the initial configuration files
+1.6. Setup folders and env file
+1.7. Setup nginx configuration
+1.8. SSL certificate with LetsEncrypt
+1.9. Requirements 2. [Install Fab-manager](#install-fabmanager)
2.1. Add docker-compose.yml file
2.2. pull images
2.3. setup database
2.4. build assets
2.5. prepare Elasticsearch (search engine)
-2.6. start all services -3. [Generate SSL certificate by Letsencrypt](#generate-ssl-certificate-by-letsencrypt) +2.6. start all services
+2.7. Generate SSL certificate by Let's encrypt 4. [Docker utils](#docker-utils) -5. [Update Fabmanager](#update-fabmanager)
+5. [Update Fab-manager](#update-fabmanager)
5.1. Steps
5.2. Good to know ## Preliminary steps + ### Setup the server There are many hosting providers on the internet, providing affordable virtual private serveurs (VPS). @@ -54,7 +56,7 @@ On DigitalOcean, create a Droplet with One-click apps **"Docker on Ubuntu 16.04 This way, Docker and Docker-compose are preinstalled. Choose a datacenter and set the hostname as your domain name. -With other providers, choose a [supported operating system](../README.md#software-stack) and install docker on it: +With other providers, choose a [supported operating system](https://github.com/LaCasemate/fab-manager/blob/master/README.md#software-stack) and install docker on it: - [Debian](https://docs.docker.com/engine/installation/linux/docker-ce/debian/) - [Ubuntu](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/) Then install [Docker Compose](https://docs.docker.com/compose/install/) @@ -79,71 +81,80 @@ Before installing fab-manager, we recommend you to: - Upgrade your system - Setup the server timezone - Add at least 2GB of swap memory -- Protect your SSH connection forcing it through a RSA key +- Protect your SSH connection by forcing it through a RSA key -You can run the following script to easily perform all these operations: +You can run the following script as root to easily perform all these operations: ```bash -cd /root -wget https://raw.githubusercontent.com/sleede/lazyscripts/master/prepare-vps.sh -chmod +x prepare-vps.sh -./prepare-vps +\curl -sSL prepare-vps.sleede.com | bash ``` + +### Retrieve the initial configuration files + +```bash +\curl -sSL https://raw.githubusercontent.com/LaCasemate/fab-manager/master/docker/setup.sh | bash +``` ### Setup folders and env file -Create the config folder: +Create the config folder, copy the environnement variables configuration file and edit it: ```bash mkdir -p /apps/fabmanager/config -cp docker/env.exemple /apps/fabmanager/config/env +cd /apps/famanager +cp example/env.exemple config/env +vi config/env +# or use your favorite text editor instead of vi (nano, ne...) ``` - -Make a copy of the **docker/env.example** file and use it as a starting point. -Set all the environment variables needed by your application. Please refer to the [FabManager README](https://github.com/LaCasemate/fab-manager/blob/master/README.md#environment-configuration) for explanations about those variables. +You need to carefully configure each variable before starting fab-manager. +Please refer to the [FabManager README](https://github.com/LaCasemate/fab-manager/blob/master/README.md#environment-configuration) for explanations about those variables. -Then, copy the previously customized `env.example` file as `/apps/fabmanager/config/env` +### Setup nginx configuration -### setup nginx file - -Create the nginx folder: +Create the nginx folder, copy the example configuration file and edit it: ```bash mkdir -p /apps/fabmanager/config/nginx +# whether you want you fab-manager to use SSL encryption or not, you should copy one of the following file +### with SSL ### +cp example/nginx_with_ssl.conf.example config/nginx/fabmanager.conf +### OR without SSL ### +cp example/nginx.conf.example config/nginx/fabmanager.conf + +vi config/nginx/fabmanager.conf +# or use your favorite text editor instead of vi (nano, ne...) ``` -Customize the docker/nginx_with_ssl.conf.example file +Customize the following values: * Replace **MAIN_DOMAIN** (example: fab-manager.com). * Replace **URL_WITH_PROTOCOL_HTTPS** (example: https://www.fab-manager.com). * Replace **ANOTHER_URL_1**, **ANOTHER_URL_2** (example: .fab-manager.fr) -**Use nginx.conf.example if you don't want SSL for your app.** - -Then, -Copy the previously customized `nginx_with_ssl.conf.example` as `/apps/fabmanager/config/nginx/fabmanager.conf` - -**OR** - -Copy the previously customized `nginx.conf.example` as `/apps/fabmanager/config/nginx/fabmanager.conf` if you do not want to use ssl (not recommended !). - ### SSL certificate with LetsEncrypt **FOLLOW THOSE INSTRUCTIONS ONLY IF YOU WANT TO USE SSL**. +If you have chosen the SSL configuration at the previous point, you must follow these instructions to make it work. Let's Encrypt is a new Certificate Authority that is free, automated, and open. Let’s Encrypt certificates expire after 90 days, so automation of renewing your certificates is important. Here is the setup for a systemd timer and service to renew the certificates and reboot the app Docker container: +Generate the dhparam.pem file ```bash mkdir -p /apps/fabmanager/config/nginx/ssl +cd /apps/fabmanager/config/nginx/ssl +openssl dhparam -out dhparam.pem 4096 ``` -Run `openssl dhparam -out dhparam.pem 4096` in the folder /apps/fabmanager/config/nginx/ssl (generate dhparam.pem file) + +Copy the initial configuration file and customize it ```bash -mkdir -p /apps/fabmanager/letsencrypt/config/ -``` -Copy the previously customized `webroot.ini.example` as `/appsfabmanager/letsencrypt/config/webroot.ini` -```bash -mkdir -p /apps/fabmanager/letsencrypt/etc/webrootauth +cd /apps/fabmanager/ +mkdir -p letsencrypt/config/ +mkdir -p letsencrypt/etc/webrootauth + +cp example/webroot.ini.example /apps/fabmanager/letsencrypt/config/webroot.ini +vi letsencrypt/config/webroot.ini +# or use your favorite text editor instead of vi (nano, ne...) ``` Run `docker pull quay.io/letsencrypt/letsencrypt:latest` @@ -176,7 +187,7 @@ Unit=letsencrypt.service WantedBy=timers.target ``` -That's all for the moment. Keep on with the installation, we'll complete that part after deployment in the [Generate SSL certificate by Letsencrypt](#generate-ssl-cert-letsencrypt). +That's all for the moment. Keep on with the installation, we'll complete that part after deployment in the [Generate SSL certificate by Let's encrypt](#generate-ssl-cert-letsencrypt). ### Requirements @@ -189,25 +200,16 @@ docker info docker-compose -v ``` -Otherwise, you can install docker to ubuntu with the following instructions : -https://docs.docker.com/engine/installation/linux/ubuntu/#install-using-the-repository - -To install docker-compose : - -```bash -curl -L https://github.com/docker/compose/releases/download/1.13.0/docker-compose-`uname -s`-`uname -m` > ./docker-compose -sudo mkdir -p /opt/bin -sudo mv docker-compose /opt/bin/ -sudo chmod +x /opt/bin/docker-compose -``` - - +Otherwise, follow the instructions provided in the section [Setup the server](#setup-the-server) to install. + ## Install Fabmanager ### Add docker-compose.yml file -Copy docker-compose.yml to your app folder `/apps/fabmanager`. +You should already have a `docker-compose.yml` file in your app folder `/apps/fabmanager`. +Otherwise, see the section [Retrieve the initial configuration files](#retrieve-config-files) to get it. + The docker-compose commands must be launched from the folder `/apps/fabmanager`. ### pull images @@ -233,11 +235,12 @@ docker-compose run --rm -e ADMIN_EMAIL=xxx -e ADMIN_PASSWORD=xxx fabmanager bund `docker-compose run --rm fabmanager bundle exec rake fablab:es_build_stats` -#### start all services +### start all services `docker-compose up -d` -### Generate SSL certificate by Letsencrypt + +### Generate SSL certificate by Let's encrypt **Important: app must be run on http before starting letsencrypt** @@ -260,9 +263,11 @@ Finally, if everything is ok, start letsencrypt timer to update the certificate ```bash sudo systemctl enable letsencrypt.timer sudo systemctl start letsencrypt.timer -(check) sudo systemctl list-timers +# check status with +sudo systemctl list-timers ``` + ## Docker utils with docker-compose ### Restart app @@ -301,7 +306,8 @@ sudo systemctl start letsencrypt.timer docker-compose run --rm -e ADMIN_EMAIL=xxx ADMIN_PASSWORD=xxx fabmanager bundle exec rake db:seed -## update Fabmanager + +## Update Fab-manager *This procedure updates fabmanager to the most recent version by default.*