Verified Commit 5a07c742 authored by Thomas Citharel's avatar Thomas Citharel 🏃🏻
Browse files

Initial commit


Signed-off-by: Thomas Citharel's avatarThomas Citharel <tcit@tcit.fr>
parents
image: tcitworld/mobilizon-documentation-ci
pages:
stage: deploy
script:
- mkdir public
- mkdocs build
- cd docs/fr && mkdocs build && cd ../../
- mv site/* public/
only:
- master
artifacts:
expire_in: 1 hour
paths:
- public
FROM alpine:latest
LABEL maintainer="Thomas Citharel <tcit@tcit.fr>"
ENV MKDOCS_VERSION=1.1.2 \
REFRESHED_AT=2020-10-22
RUN \
apk add --update \
ca-certificates \
bash \
git \
openssh \
python3 \
python3-dev \
py3-pip \
build-base && \
pip install --upgrade pip && \
pip install mkdocs==${MKDOCS_VERSION} mkdocs-material pymdown-extensions pygments mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude && \
rm -rf /tmp/* /var/tmp/* /var/cache/apk/* /var/cache/distfiles/*
# About Mobilizon
<p align="center">
<a href="https://joinmobilizon.org">
<img src="https://lutim.cpy.re/qVYC86G9.png" alt="Mobilizon">
</a>
</p>
Mobilizon is your federated organization and mobilization platform. Gather people with a convivial, ethical, and emancipating tool.
<p align="center">
<strong>Developed with ♥ by <a href="https://framasoft.org">Framasoft</a></strong>
</p>
<p align="center">
<a href="https://framasoft.org">
<img width="150px" src="https://lutim.cpy.re/Prd3ci7G.png" alt="Framasoft logo"/>
</a>
</p>
## Introduction
Mobilizon is a tool designed to create platforms for managing communities and events. Its purpose is to help as many people as possible to free themselves from Facebook groups and events, from Meetup, etc.
The Mobilizon software is under a Free licence, so anyone can host a Mobilizon server, called an instance. These instances may federate with each other, so any person with an account on *ExampleMeet* will be able to register to an event created on *SpecimenEvent*.
## ✨ Features
### 👤 Identities
Do you want to separate your family gatherings from your associative activities or militant mobilizations?
You will have the power to create multiple identities from the same account, like so many social masks.
---
### 📅 Events and groups
Create your events and make sure they will appeal to everybody.
Privacy settings and participants roles are supported.
There's no lock-in, you can interact with the event without registration.
---
## Contributing
We appreciate any contribution to Mobilizon. Check our [Contributing](contribute/index.md) page for more information.
## Links
### Learn more
* 🌐 Official website: [https://joinmobilizon.org](https://joinmobilizon.org)
* 💻 Source: [https://framagit.org/framasoft/mobilizon](https://framagit.org/framasoft/mobilizon)
* 📝 Wiki: [https://framagit.org/framasoft/mobilizon/wikis/home](https://framagit.org/framasoft/mobilizon/wikis/home)
### Discuss
* 💬 Matrix: `#Mobilizon:matrix.org` [Riot](https://riot.im/app/#/room/#Mobilizon:matrix.org)
* IRC: `#mobilizon` on Freenode
* 🗣️ Forum: [https://framacolibri.org/c/mobilizon](https://framacolibri.org/c/mobilizon)
### Follow
* 🐘 Mastodon: [https://framapiaf.org/@mobilizon](https://framapiaf.org/@mobilizon)
* 🐦 Twitter [https://twitter.com/@joinmobilizon](https://twitter.com/@joinmobilizon)
Note: Most federation code comes from [Pleroma](https://pleroma.social), which is `Copyright © 2017-2019 Pleroma Authors - AGPL-3.0`
# Maintenance tasks
## Installation
Generates new configuration files.
!!! warning
This command generates configuration for your Mobilizon instance and should be run only once when installing.
If any options are left unspecified, you will be prompted interactively.
```bash
mix mobilizon.instance gen [<options>]
```
### Options
* `-f`, `--force` Whether to erase existing files
* `-o`, `--output PATH` The path to output the `prod.secret.exs` file. Defaults to `config/prod.secret.exs`.
* `--output-psql PATH` The path to output the SQL script. Defaults to `setup_db.psql`.
* `--domain DOMAIN` The instance's domain
* `--instance-name INSTANCE_NAME` The instance's name
* `--admin-email ADMIN_EMAIL` The administrator's email
* `--dbhost HOSTNAME` The database hostname of the PostgreSQL database to use
* `--dbname DBNAME` The name of the database to use
* `--dbuser DBUSER` The database user (aka role) to use for the database connection
* `--dbpass DBPASS` The database user's password to use for the database connection
* `--dbport DBPORT` The database port
# Manage actors
!!! tip "Environment"
You need to run these commands with the appropriate environment loaded, so probably prefix with `MIX_ENV=prod`.
## List all available commands
```bash
mix mobilizon.actors
```
## Show an actors details
```bash
mix mobilizon.actors.show
```
In addition to basic informations, it also tells which user the profile belongs to, if local.
\ No newline at end of file
# Manage users
!!! tip "Environment"
You need to run these commands with the appropriate environment loaded, so probably prefix with `MIX_ENV=prod`.
## List all available commands
```bash
mix mobilizon.users
```
## Create a new user
```bash
mix mobilizon.users.new <email> [<options>]
```
### Options
* `--password <password>`/ `-p <password>` - the user's password. If this option is missing, a password will be generated randomly.
* `--moderator` - make the user a moderator
* `--admin` - make the user an admin
## Show an user's details
Displays if the user has confirmed their email, if they're a moderator or an admin and their profiles.
```bash
mix mobilizon.users.show <email>
```
## Modify an user
```bash
mix mobilizon.users.modify <email>
```
### Options
* `--email <email>` - the user's new email
* `--password <password>` - the user's new password.
* `--user` - make the user a regular user
* `--moderator` - make the user a moderator
* `--admin` - make the user an admin
* `--enable` - enable the user
* `--disable` - disable the user
## Delete an user
```bash
mix mobilizon.users.delete <email>
```
### Options
* `--assume_yes`/`-y` Don't ask for confirmation
* `--keep_email`/`-k` Keep user entry with just email information (to prevent future registrations with same email)
\ No newline at end of file
# Relay
Manages remote relays
!!! tip "Environment"
You need to run these commands with the appropriate environment loaded, so probably prefix with `MIX_ENV=prod`.
## Make your instance follow a mobilizon instance
```bash
mix mobilizon.relay follow <relay_host>
```
Example:
```bash
mix mobilizon.relay follow example.org
```
## Make your instance unfollow a mobilizon instance
```bash
mix mobilizon.relay unfollow <relay_host>
```
Example:
```bash
mix mobilizon.relay unfollow example.org
```
# Authentification
## LDAP
Use LDAP for user authentication. When a user logs in to the Mobilizon instance, the email and password will be verified by trying to authenticate
(bind) to an LDAP server. If a user exists in the LDAP directory but there is no account with the same email yet on the Mobilizon instance then a new
Mobilizon account will be created (without needing email confirmation) with the same email as the LDAP email name.
!!! tip
As Mobilizon uses email for login and LDAP bind is often done with account UID/CN, we need to start by searching for LDAP account matching with this email. LDAP search without bind is often disallowed, so you'll probably need an admin LDAP user.
Change authentification method:
```elixir
config :mobilizon,
Mobilizon.Service.Auth.Authenticator,
Mobilizon.Service.Auth.LDAPAuthenticator
```
LDAP configuration under `:mobilizon, :ldap`:
* `enabled`: enables LDAP authentication
* `host`: LDAP server hostname
* `port`: LDAP port, e.g. 389 or 636
* `ssl`: true to use SSL, usually implies the port 636
* `sslopts`: additional SSL options
* `tls`: true to start TLS, usually implies the port 389
* `tlsopts`: additional TLS options
* `base`: LDAP base, e.g. "dc=example,dc=com"
* `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base"
* `require_bind_for_search` whether admin bind is required to perform search
* `bind_uid` the admin uid/cn for binding before searching
* `bind_password` the admin password for binding before searching
Example:
```elixir
config :mobilizon, :ldap,
enabled: true,
host: "localhost",
port: 636,
ssl: true,
sslopts: [],
tls: true,
tlsopts: [],
base: "ou=users,dc=example,dc=local",
uid: "cn",
require_bind_for_search: true,
bind_uid: "admin_account",
bind_password: "some_admin_password"
```
## OAuth
Mobilizon currently supports the following providers:
* [Discord](https://github.com/schwarz/ueberauth_discord)
* [Facebook](https://github.com/ueberauth/ueberauth_facebook)
* [Github](https://github.com/ueberauth/ueberauth_github)
* [Gitlab](https://github.com/mtchavez/ueberauth_gitlab) (including self-hosted)
* [Google](https://github.com/ueberauth/ueberauth_google)
* [Keycloak](https://github.com/Rukenshia/ueberauth_keycloak) (through OpenID Connect)
* [Twitter](https://github.com/Rukenshia/ueberauth_keycloak)
Support for [other providers](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies) can easily be added if requested.
!!! tip
We advise to look at each provider's README file for eventual specific instructions.
You'll have to start by registering an app at the provider. Be sure to activate features like "Sign-in with" and "emails" scope, as Mobilizon needs users emails to register them.
Add the configured providers to configuration (you may find the appropriate scopes on the provider's API documentation):
```elixir
config :ueberauth,
Ueberauth,
providers: [
gitlab: {Ueberauth.Strategy.Gitlab, [default_scope: "read_user"]},
keycloak: {Ueberauth.Strategy.Keycloak, [default_scope: "email"]}
# ...
]
```
In order for the « Sign-in with » buttons to be added on Register and Login pages, list your providers:
```elixir
config :mobilizon, :auth,
oauth_consumer_strategies: [
:gitlab,
{:keycloak, "My corporate account"}
# ...
]
```
!!! note
If you use the `{:provider_id, "Some label"}` form, the label will be used inside the buttons on Register and Login pages.
Finally add the configuration for each specific provider. The Client ID and Client Secret are at least required:
```elixir
config :ueberauth, Ueberauth.Strategy.Facebook.OAuth,
client_id: "some_numeric_id",
client_secret: "some_secret"
keycloak_url = "https://some-keycloak-instance.org"
# Realm may be something else than master
config :ueberauth, Ueberauth.Strategy.Keycloak.OAuth,
client_id: "some_id",
client_secret: "some_hexadecimal_secret",
site: keycloak_url,
authorize_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/auth",
token_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/token",
userinfo_url: "#{keycloak_url}/auth/realms/master/protocol/openid-connect/userinfo",
token_method: :post
```
\ No newline at end of file
# Email
Mobilizon requires a SMTP server to deliver emails. Using 3rd-party mail providers (Mandrill, SendGrid, Mailjet, …) will be possible in the future.
## SMTP configuration
Mobilizon default settings assumes a SMTP server listens on `localhost`, port `25`. To specify a specific server and credentials, you can add the following section in your `prod.secret.exs` file and modify credentials to your needs.
```elixir
config :mobilizon, Mobilizon.Web.Email.Mailer,
adapter: Bamboo.SMTPAdapter,
server: "localhost",
hostname: "localhost",
# usually 25, 465 or 587
port: 25,
username: nil,
password: nil,
# can be `:always` or `:never`
tls: :if_available,
allowed_tls_versions: [:tlsv1, :"tlsv1.1", :"tlsv1.2"],
retries: 1,
# can be `true`
no_mx_lookups: false,
# can be `:always`. If your smtp relay requires authentication set it to `:always`.
auth: :if_available
```
!!! tip
The hostname option sets the FQDN to the header of your emails, its optional, but if you don't set it, the underlying `gen_smtp` module will use the hostname of your machine, like `localhost`.
You'll need to restart Mobilizon to recompile the app and apply the new settings.
\ No newline at end of file
# Geocoders
Geocoding is the ability to match an input **string representing a location - such as an address - to geographical coordinates**.
Reverse geocoding is logically the opposite, matching **geographical coordinates to names of places**.
This is needed to set correct address for events, and more easily find events with geographical data, for instance if you want to discover events happening near your current position.
However, providing a geocoding service is quite expensive, especially if you want to cover the whole Earth.
!!! note "Hardware setup"
To give an idea of what hardware is required to self-host a geocoding service, we successfully installed and used [Addok](#addok), [Pelias](#pelias) and [Mimirsbrunn](#mimirsbrunn) on a 8 cores/16GB RAM machine without any issues **importing only European addresses and data**.
!!! tip "Advised provider"
We had best results using the [Pelias](#pelias) geocoding provider.
## Change geocoder
To change geocoder backend, you need to add the following line in `prod.secret.exs`:
```elixir
config :mobilizon, Mobilizon.Service.Geospatial,
service: Mobilizon.Service.Geospatial.Nominatim
```
And change `Nominatim` to one of the supported geocoders. Depending on the provider, you'll also need to add some special config to specify eventual endpoints or API keys.
For instance, when using `Mimirsbrunn`, you'll need the following configuration:
```elixir
config :mobilizon, Mobilizon.Service.Geospatial,
service: Mobilizon.Service.Geospatial.Mimirsbrunn
config :mobilizon, Mobilizon.Service.Geospatial.Mimirsbrunn,
endpoint: "https://my-mimir-instance.tld"
```
## List of supported geocoders
This is the list of all geocoders supported by Mobilizon. The current default one is [Nominatim](#nominatim) and uses the official OpenStreetMap instance.
### Nominatim
[Nominatim](https://wiki.openstreetmap.org/wiki/Nominatim) is a GPL-2.0 licenced tool to search data by name and address. It's written in C and PHP and uses PostgreSQL.
It's the current default search tool on the [OpenStreetMap homepage](https://www.openstreetmap.org).
!!! warning "Terms"
When using the official Nominatim OpenStreetMap instance (default endpoint for this geocoder if not configured otherwise), you need to read and accept the [Usage Policy](https://operations.osmfoundation.org/policies/nominatim).
!!! danger "Limitations"
Autocomplete is not possible using Nominatim, you'll obtain no suggestions while typing.
Several companies provide hosted instances of Nominatim that you can query via an API, for example see [MapQuest Open Initiative](https://developer.mapquest.com/documentation/open/nominatim-search).
** Default configuration **
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.Nominatim,
endpoint: "https://nominatim.openstreetmap.org",
api_key: nil
```
### Addok
[Addok](https://github.com/addok/addok) is a MIT licenced search engine for address (and only address). It's written in Python and uses Redis.
It's used by French government for [adresse.data.gouv.fr](https://adresse.data.gouv.fr).
!!! warning "Terms"
When using France's Addok instance at `api-adresse.data.gouv.fr` (default endpoint for this geocoder if not configured otherwise), you need to read and accept the [GCU](https://adresse.data.gouv.fr/cgu) (in French).
** Default configuration **
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.Addok,
endpoint: "https://api-adresse.data.gouv.fr"
```
The default endpoint is limited to France. Geo coding outside of France will return an empty result. Moreover, as France is implicit for this endpoint, country is not part of the result.
To conform to `Provider` interface, this provider return "France" as the country.
If plugged to another endpoint, in another country, it could be useful to change the default country. This can be done in `prod.secret.exs`:
** change endpoint default country **
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.Addok,
endpoint: "https://another-endpoint.tld"
default_country: "Country"
```
### Photon
[Photon](https://photon.komoot.de/) is an Apache 2.0 licenced search engine written in Java and powered by ElasticSearch.
!!! warning "Terms"
The terms of use for the official instance (default endpoint for this geocoder if not configured otherwise) are simply the following:
> You can use the API for your project, but please be fair - extensive usage will be throttled. We do not guarantee for the availability and usage might be subject of change in the future.
** Default configuration **
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.Photon,
endpoint: "https://photon.komoot.de"
```
### Pelias
[Pelias](https://github.com/pelias/pelias) is a MIT licensed geocoder composed of several services written in NodeJS. It's powered by ElasticSearch.
There's [Geocode Earth](https://geocode.earth/) SAAS that provides a Pelias API.
They offer discounts for Open-Source projects. [See the pricing](https://geocode.earth/).
**Configuration example**
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.Pelias,
endpoint: nil
```
### Mimirsbrunn
[Mimirsbrunn](https://github.com/CanalTP/mimirsbrunn) is an AGPL-3.0 licensed geocoding written in Rust and powered by ElasticSearch.
Mimirsbrunn is used by [Qwant Maps](https://www.qwant.com/maps) and [Navitia](https://www.navitia.io).
** Default configuration **
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.Mimirsbrunn,
endpoint: nil
```
### Google Maps
[Google Maps](https://developers.google.com/maps/documentation/geocoding/intro) is a proprietary service that provides APIs for geocoding.
They don't have a free plan, but offer credit when creating a new account. [See the pricing](https://cloud.google.com/maps-platform/pricing/).
** Default configuration **
!!! note
`fetch_place_details` tells GoogleMaps to also fetch some details on a place when geocoding. It can be more expensive, since you're doing two requests to Google instead of one.
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.GoogleMaps,
api_key: nil,
fetch_place_details: true
```
### MapQuest
[MapQuest](https://developer.mapquest.com/documentation/open/geocoding-api/) is a proprietary service that provides APIs for geocoding.
They offer a free plan. [See the pricing](https://developer.mapquest.com/plans).
** Default configuration **
```elixir
config :mobilizon, Mobilizon.Service.Geospatial.MapQuest,
api_key: nil
```
### More geocoding services
Geocoding implementations are simple modules that need to implement the [`Mobilizon.Service.Geospatial.Provider` behaviour](https://framasoft.frama.io/mobilizon/backend/Mobilizon.Service.Geospatial.Provider.html), so feel free to write your own!
# 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
```
# Dependencies
## Debian / Ubuntu and derivatives
This documentation is appropriate for Debian 10 (Buster) and Ubuntu 18.04 LTS.
### 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.
### 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:
```bash
sudo apt install build-essential curl unzip vim openssl git cmake
```
### Web server
We only officially support nginx.
```bash
sudo apt install nginx
```
### HTTPS Certificates
Then we need to install [certbot](https://certbot.eff.org/), a tool to ask for free Let's Encrypt HTTPS certificates.
```bash
sudo apt install certbot
```
You can use certbot with web server plugins or manually. See [Certbot's documentation](https://certbot.eff.org/instructions).
### NodeJS
We install the latest NodeJS version by adding NodeSource repos and installing NodeJS:
Head over to [this page](https://github.com/nodesource/distributions/blob/master/README.md#table-of-contents) and follow the instructions for `Node.js v12.x`.
!!! info
Unless stated otherwise, Mobilizon always supports only the latest LTS version of NodeJS.
!!! tip
NodeSource repos only gives updates for a specific version of NodeJS (it doesn't upgrade itself to a new major version). When a new major version of NodeJS is released, you need to remove the old repo and add the new one.
### Yarn
Mobilizon uses [Yarn](https://yarnpkg.com/) to manage NodeJS packages, so we need to install it as well.
Follow the instructions on [this page](https://yarnpkg.com/en/docs/install#debian-stable) to add Yarn's repository and install it.
!!! info
It is also possible to install `yarn` directly with `npm`:
```bash
npm install -g yarn
```.
You need to make sure npm's binary packages folder in your `$PATH` afterwards to use `yarn`.