Source¶

Pre-requisites¶

• A Linux machine with root access
• A domain name (or subdomain) for the Mobilizon server, e.g. your-mobilizon-domain.com
• An SMTP server to deliver emails

Security¶

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.

Dependencies¶

Mobilizon requires Elixir, NodeJS and PostgreSQL among other things. Prefer to install Elixir and NodeJS from their official repositories instead of your distribution's packages (more on that below).

Recommended versions:

• Elixir 1.15+
• NodeJS 20+
• PostgreSQL 13+

Upgrade system¶

Just to be sure your system is up-to-date before doing anything else:

sudo apt update
sudo apt dist-upgrade

Basic tools¶

We begin by making sure some basic tools are installed:

sudo apt install build-essential curl unzip openssl git cmake file

sudo pacman -S base-devel curl unzip openssl git cmake file

Web server¶

We only officially support nginx.

sudo apt install nginx

HTTPS Certificates¶

Then we need to install certbot, a tool to ask for free Let's Encrypt HTTPS certificates.

sudo apt install certbot

You can use certbot with web server plugins or manually. See Certbot's documentation.

NodeJS¶

We install the latest NodeJS version by adding NodeSource repos and installing NodeJS:

Head over to this page and follow the instructions for Node.js v20.x.

Erlang and Elixir¶

The packages from Debian or Ubuntu are badly packaged and often out of date, so we need to add one final source repository.

Follow the instructions for your system on this page to install the Erlang and Elixir packages.

For Debian/Ubuntu, to get the latest Erlang/Elixir versions, you should install the Erlang Solutions repo and then the Erlang and Elixir packages. It should come down to the following steps:

Add the following content to /etc/apt/sources.list.d/erlang-solutions.list :

deb http://binaries2.erlang-solutions.com/debian/ {{oscodename}} contrib
deb http://binaries2.erlang-solutions.com/debian/ {{oscodename}} contrib

Where {{oscodename}} stands for the codename of the Debian/Ubuntu release in use.

Download and import the repository GPG key :

wget https://binaries2.erlang-solutions.com/GPG-KEY-pmanager.asc
apt-key add GPG-KEY-pmanager.asc
rm GPG-KEY-pmanager.asc

Install Erlang & Elixir packages :

apt update
apt install esl-erlang
apt install elixir

PostgreSQL and PostGIS¶

Mobilizon uses the PostgreSQL database, and the PostgreSQL Postgis extension to store geographical data into PostgreSQL.

sudo apt install postgresql postgresql-contrib
sudo apt install --install-recommends postgis

sudo -iu postgres
initdb -D /var/lib/postgres/data

After that we can enable and start the PostgreSQL service.

sudo systemctl --now enable postgresql

Misc¶

We need the following tools to handle and optimize pictures that are uploaded on Mobilizon.

sudo apt install imagemagick webp

The following packages are optional, Mobilizon can run without them, but if found they will be used to optimize user's pictures so that they are lighter.

sudo apt install gifsicle jpegoptim optipng pngquant

Once finished, let's head back to the install guide.

Arch Linux¶

Run the following command to install all at once:

sudo pacman -S nodejs postgresql openssl git wget unzip base-devel nginx elixir postgis imagemagick file libwebp

Now that dependencies are installed, before running Mobilizon you should start PostgreSQL:

sudo systemctl --now enable postgresql

Once finished, let's head back to the install guide.

Other distributions¶

Feel free to update this file in a merge request!

Setup¶

We're going to use a dedicated mobilizon user with /home/mobilizon home:

sudo adduser --shell /bin/false mobilizon

sudo pw useradd -n mobilizon -d /home/mobilizon -s /usr/local/bin/bash -m 
sudo passwd mobilizon

Then let's connect as this user:

sudo -i -u mobilizon

Let's start by cloning the repository in a directory named live:

git clone https://framagit.org/framasoft/mobilizon live && cd live

Then pick the latest release (you can get the number version from https://framagit.org/framasoft/mobilizon/-/releases). For instance if the version is 1.0.6:

git checkout 1.0.6

Installing dependencies¶

Install Elixir dependencies

mix deps.get

Then compile these dependencies and Mobilizon (this can take a few minutes, and can output all kinds of warnings, such as depreciation issues)

MIX_ENV=prod mix compile

Install the Javascript dependencies

npm install

Finally, we can build the front-end (this can take a few seconds).

NODE_BUILD_MEMORY=1024

npm run build

Create a digest of the static assets

MIX_ENV=prod mix phx.digest

Configuration¶

Mobilizon provides a command line tool to generate configuration

MIX_ENV=prod mix mobilizon.instance gen

This will ask you questions about your setup and your instance to generate a runtime.exs file in the config/ folder, and a setup_db.psql file to setup the database.

Database setup¶

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.

Exit running as the mobilizon user (as it shouldn't have root/sudo rights) and execute in the /home/mobilizon/live directory:

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:

sudo -i -u mobilizon
cd live

Database Migration¶

Run database migrations:

MIX_ENV=prod mix ecto.migrate

You will have to do this again after most updates.

Uploads¶

The default uploads directory is set to /var/lib/mobilizon/uploads, so we need to create it. The location can be changed with the following configuration:

config :mobilizon, Mobilizon.Web.Upload.Uploader.Local, uploads: "/var/lib/mobilizon/uploads"

Other directories created below can have their path changed as well.

• Create the media directory and other needed directories

  mkdir -p /var/lib/mobilizon/uploads /var/lib/mobilizon/uploads/exports/csv /var/lib/mobilizon/sitemap /var/lib/mobilizon/timezones /var/lib/mobilizon/geo
  

• Make sure the uploaded files have the proper owner. Mobilizon needs write access to this folder.

  chown -R mobilizon:mobilizon /var/lib/mobilizon/uploads
  

Services¶

We can quit using the mobilizon user again.

Systemd¶

Copy the support/systemd/mobilizon-source.service to /etc/systemd/system/mobilizon.service.

sudo cp support/systemd/mobilizon-source.service /etc/systemd/system/mobilizon.service

Reload Systemd to detect your new file

sudo systemctl daemon-reload

And enable the service

sudo systemctl enable --now mobilizon.service

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¶

Nginx¶

Copy the file from support/nginx/mobilizon-source.conf to /etc/nginx/sites-available/mobilizon.conf.

sudo cp support/nginx/mobilizon-source.conf /etc/nginx/sites-available/mobilizon.conf

Then symlink the file into the /etc/nginx/sites-enabled directory.

sudo ln -s /etc/nginx/sites-available/mobilizon.conf /etc/nginx/sites-enabled/

Edit the file /etc/nginx/sites-available/mobilizon.conf and adapt it to your own configuration.

Test the configuration with sudo nginx -t and reload nginx with sudo systemctl reload nginx.

Let's Encrypt¶

The nginx configuration template handles the HTTP-01 challenge with the webroot plugin:

sudo mkdir /var/www/certbot

Run certbot with (don't forget to adapt the command)

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 sudo 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:

sudo -i -u mobilizon
cd live

Create a new user:

 MIX_ENV=prod mix mobilizon.users.new "your@email.com" --admin --password "Y0urP4ssw0rd"

See the full documentation for this command.

You may now login with your credentials and discover Mobilizon. Feel free to explore configuration documentation as well.

Suggested tasks¶

Configure emails¶

The default Mobilizon configuration assumes a local SMTP server is available on the same server. To tweak this for your own setup, see this page.

Configure 3^rd-party auth¶

Mobilizon can use LDAP or OAuth-based login providers (Facebook, Google, etc.) to help register or login users. Configuration can be found here.

Configure geocoders¶

This will allow the address autocomplete field to provide addresses when editing an event. The default value uses OpenStreetMap's Nominatim provider but you can change it to the provider of your choice.

Geolocation databases¶

Mobilizon can use geolocation from MMDB format data from sources like MaxMind GeoIP databases or db-ip.com 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. Finish by restarting the mobilizon service.

Mobilizon will only show a warning at startup if the database is missing, but it isn't required.