From e7757d406838538372bb3323bff1e79561896987 Mon Sep 17 00:00:00 2001 From: Thomas Citharel Date: Tue, 16 Jun 2020 10:57:11 +0200 Subject: [PATCH] Improve installation docs Signed-off-by: Thomas Citharel --- docs/administration/configure/index.md | 13 ++++ docs/administration/dependencies.md | 9 +++ docs/administration/index.md | 83 +++++++++++++++++++++++--- support/nginx/mobilizon.conf | 25 ++++++-- support/systemd/mobilizon.service | 6 +- 5 files changed, 122 insertions(+), 14 deletions(-) create mode 100644 docs/administration/configure/index.md diff --git a/docs/administration/configure/index.md b/docs/administration/configure/index.md new file mode 100644 index 000000000..8cce1d68f --- /dev/null +++ b/docs/administration/configure/index.md @@ -0,0 +1,13 @@ +# Configuration + +Basic Mobilizon configuration can be handled through the Admin panel in the UI. + +Core mobilizon configuration must be managed into the `config/prod.secret.exs` file. +After performing changes to this file, you have to recompile the mobilizon app with: +```bash +MIX_ENV=prod mix compile +``` +and then restart the Mobilizon service: +``` +systemctl restart mobilizon +``` diff --git a/docs/administration/dependencies.md b/docs/administration/dependencies.md index 175a966ee..130fee800 100644 --- a/docs/administration/dependencies.md +++ b/docs/administration/dependencies.md @@ -9,6 +9,15 @@ This documentation is appropriate for Debian 10 (Buster) and Ubuntu 18.04 LTS. We advise to make sure your webserver is secure enough. For instance you can require authentication through SSH keys and not passwords, install Fail2Ban to block repeated login attempts and block unused ports by installing and configuring a firewall. +### Upgrade system + +Just to be sure your system is up-to-date before doing anything else: + +```bash +sudo apt update +sudo apt dist-upgrade +``` + ### Basic tools We begin by making sure some basic tools are installed: diff --git a/docs/administration/index.md b/docs/administration/index.md index 1496ab13e..922797100 100644 --- a/docs/administration/index.md +++ b/docs/administration/index.md @@ -7,7 +7,7 @@ ## Pre-requisites * A Linux machine with **root access** -* A **domain name** (or subdomain) for the Mobilizon server, e.g. `example.net` +* A **domain name** (or subdomain) for the Mobilizon server, e.g. `your-mobilizon-domain.com` * An **SMTP server** to deliver emails ## Dependencies @@ -53,10 +53,13 @@ Install Elixir dependencies mix deps.get ``` -Then compile these dependencies and Mobilizon (this can take a few minutes) +!!! note + When asked for `Shall I install Hex?` or `Shall I install rebar3?`, hit the enter key to confirm. + +Then compile these dependencies and Mobilizon (this can take a few minutes, and can output all kinds of warnings, such as depreciation issues) ```bash -mix compile +MIX_ENV=prod mix compile ``` Go into the `js/` directory @@ -73,7 +76,7 @@ yarn install Finally, we can build the front-end (this can take a few seconds) ```bash -NODE_ENV=production yarn run build +yarn run build ``` Let's go back to the main directory @@ -86,7 +89,7 @@ cd ../ Mobilizon provides a command line tool to generate configuration ```bash -mix mobilizon.instance gen +MIX_ENV=prod mix mobilizon.instance gen ``` This will ask you questions about your setup and your instance to generate a `prod.secret.exs` file in the `config/` folder, and a `setup_db.psql` file to setup the database. @@ -95,11 +98,27 @@ This will ask you questions about your setup and your instance to generate a `pr The `setup_db.psql` file contains SQL instructions to create a PostgreSQL user and database with the chosen credentials and add the required extensions to the Mobilizon database. -Execute +Exit running as the mobilizon user (as it shouldn't have `root`/`sudo` rights) and execute in the `/home/mobilizon/live` directory: ```bash sudo -u postgres psql -f setup_db.psql ``` +It should output something like: +``` +CREATE ROLE +CREATE DATABASE +You are now connected to database "mobilizon_prod" as user "postgres". +CREATE EXTENSION +CREATE EXTENSION +CREATE EXTENSION +``` + +Let's get back to our `mobilizon` user: +```bash +sudo -i -u mobilizon +cd live +``` + !!! warning When it's done, don't forget to remove the `setup_db.psql` file. @@ -122,6 +141,8 @@ You will have to do this again after most updates. ## Services +We can quit using the `mobilizon` user again. + ### Systemd Copy the `support/systemd/mobilizon.service` to `/etc/systemd/system`. @@ -148,6 +169,12 @@ It will run Mobilizon and enable startup on boot. You can follow the logs with sudo journalctl -fu mobilizon.service ``` +You should see something like this: +``` +Running Mobilizon.Web.Endpoint with cowboy 2.8.0 at :::4000 (http) +Access Mobilizon.Web.Endpoint at https://your-mobilizon-domain.com +``` + The Mobilizon server runs on port 4000 on the local interface only, so you need to add a reverse-proxy. ## Reverse proxy @@ -170,12 +197,54 @@ Edit the file `/etc/nginx/sites-available` and adapt it to your own configuratio Test the configuration with `sudo nginx -t` and reload nginx with `systemctl reload nginx`. +### Let's Encrypt + +The nginx configuration template handles the HTTP-01 challenge with the webroot plugin: +```bash +sudo mkdir /var/www/certbot +``` + +Run certbot with (don't forget to adapt the command) +```bash +sudo certbot certonly --rsa-key-size 4096 --webroot -w /var/www/certbot/ --email your@email.com --agree-tos --text --renew-hook "/usr/sbin/nginx -s reload" -d your-mobilizon-domain.com +``` + +Then adapt the nginx configuration `/etc/nginx/sites-available/mobilizon.conf` by uncommenting certificate paths and removing obsolete blocks. + +Finish by testing the configuration with `sudo nginx -t` and reloading nginx with `systemctl reload nginx`. + +You should now be able to load https://your-mobilizon-domain.com inside your browser. + +## Creating your first user + +Login back as the `mobilizon` system user: + +```bash +sudo -i -u mobilizon +cd live +``` + +Create a new user: +``` + MIX_ENV=prod mix mobilizon.users.new "your@email.com" --admin --password "Y0urP4ssw0rd" +``` + +!!! danger + Don't forget to prefix the command with an empty space so that the chosen password isn't kept in your shell history. + +!!! tip + You can ignore the `--password` option and Mobilizon will generate one for you. + +See the [full documentation](./CLI tasks/manage_users.md#create-a-new-user) for this command. + +You may now login with your credentials and discover Mobilizon. Feel free to explore [configuration documentation](./configure) as well. + ## Optional tasks ### Geolocation databases Mobilizon can use geolocation from MMDB format data from sources like [MaxMind GeoIP](https://dev.maxmind.com/geoip/geoip2/geolite2/) databases or [db-ip.com](https://db-ip.com/db/download/ip-to-city-lite) databases. This allows showing events happening near the user's location. -You will need to download the City database and put it into `priv/data/GeoLite2-City.mmdb`. +You will need to download the City database and put it into `priv/data/GeoLite2-City.mmdb`. Finish by restarting the `mobilizon` service. Mobilizon will only show a warning at startup if the database is missing, but it isn't required. \ No newline at end of file diff --git a/support/nginx/mobilizon.conf b/support/nginx/mobilizon.conf index 762fa94f4..7ff6a1690 100644 --- a/support/nginx/mobilizon.conf +++ b/support/nginx/mobilizon.conf @@ -11,7 +11,15 @@ server { listen 80; listen [::]:80; - return 301 https://$server_name$request_uri; + + # Remove once HTTPS is setup + location ^~ '/.well-known/acme-challenge' { + root /var/www/certbot; + default_type "text/plain"; + } + + # Uncomment once HTTPS is setup + # return 301 https://$server_name$request_uri; } server { @@ -21,9 +29,10 @@ server { listen [::]:443 ssl http2; ssl_session_timeout 5m; - ssl_trusted_certificate /etc/letsencrypt/live/example.tld/fullchain.pem; - ssl_certificate /etc/letsencrypt/live/example.tld/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/example.tld/privkey.pem; + # Uncomment once you get the certificates + # ssl_trusted_certificate /etc/letsencrypt/live/example.tld/fullchain.pem; + # ssl_certificate /etc/letsencrypt/live/example.tld/fullchain.pem; + # ssl_certificate_key /etc/letsencrypt/live/example.tld/privkey.pem; # Add TLSv1.3 if it's supported by your system ssl_protocols TLSv1.2; @@ -46,6 +55,12 @@ server { # the nginx default is 1m, not enough for large media uploads client_max_body_size 16m; + # Let's Encrypt keeps its files here + location ^~ '/.well-known/acme-challenge' { + root /var/www/certbot; + default_type "text/plain"; + } + location / { gzip off; proxy_http_version 1.1; @@ -65,7 +80,7 @@ server { } location ~* \.(css|js)$ { - root /var/www/mobilizon/priv/static; + root /home/mobilizon/live/priv/static; etag off; expires 1y; access_log off; diff --git a/support/systemd/mobilizon.service b/support/systemd/mobilizon.service index 6fc25bb6f..b5b97d082 100644 --- a/support/systemd/mobilizon.service +++ b/support/systemd/mobilizon.service @@ -4,13 +4,15 @@ After=network.target postgresql.service [Service] User=mobilizon -WorkingDirectory=/home/mobilizon/mobilizon -ExecStart=/usr/local/bin/mix phx.server +WorkingDirectory=/home/mobilizon/live +ExecStart=/usr/bin/env mix phx.server ExecReload=/bin/kill $MAINPID KillMode=process Restart=on-failure Environment=MIX_ENV=prod +SyslogIdentifier=mobilizon + ; Some security directives. ; Use private /tmp and /var/tmp folders inside a new file system namespace, which are discarded after the process stops. PrivateTmp=true