Verified Commit 84076b61 authored by Thomas Citharel's avatar Thomas Citharel 🏃🏻
Browse files

Rework docs


Signed-off-by: Thomas Citharel's avatarThomas Citharel <tcit@tcit.fr>
parent 59eda9d2
FROM squidfunk/mkdocs-material
RUN pip install 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/*
\ No newline at end of file
......@@ -2,26 +2,40 @@
Mobilizon provides commands to perform some tasks.
!!! tip "Environment"
You need to run these commands with the appropriate environment loaded, so probably prefix with `MIX_ENV=prod`.
=== "Releases"
The commands need to be called like this:
```bash
sudo -u mobilizon ./bin/mobilizon_ctl command.subcommand
```
The commands are documented as if they were being used a source installation:
```bash
MIX_ENV=prod mix mobilizon.command.subcommand
```
For instance, creating a new admin would be something like:
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users.new "your@email.com" --admin --password "Y0urP4ssw0rd"
```
If you use Elixir releases (such as [Docker](../docker.md)), the commands need to be changed like this:
```bash
mobilizon_ctl command.subcommand
```
=== "Docker"
For instance, creating a new admin without Docker would be something like:
```bash
MIX_ENV=prod mix mobilizon.users.new "your@email.com" --admin --password "Y0urP4ssw0rd"
```
The commands need to be called like this:
```bash
mobilizon_ctl command.subcommand
```
Inside Docker, it would be something like:
```bash
docker-compose exec mobilizon mobilizon_ctl users.new "your@email.com" --admin --password "Y0urP4ssw0rd"
```
\ No newline at end of file
For instance, creating a new admin would be something like:
```bash
docker-compose exec mobilizon mobilizon_ctl users.new "your@email.com" --admin --password "Y0urP4ssw0rd"
```
=== "Source"
!!! tip "Environment"
You need to run these commands with the appropriate environment loaded, so make sure they're alwayed prefixed with `MIX_ENV=prod`.
The commands need to be called like this:
```bash
MIX_ENV=prod mix mobilizon.command.subcommand
```
For instance, creating a new admin would be something like:
```bash
MIX_ENV=prod mix mobilizon.users.new "your@email.com" --admin --password "Y0urP4ssw0rd"
```
......@@ -9,10 +9,18 @@ Generates new configuration files.
If any options are left unspecified, you will be prompted interactively.
```bash
mix mobilizon.instance gen [<options>]
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl instance gen [<options>]
```
=== "Docker"
You shouldn't need to run this task on Docker.
=== "Source"
```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`.
......@@ -34,6 +42,17 @@ mix mobilizon.instance gen [<options>]
Fixes an issue with media files that were not attached to their entities when included directly in body text, meaning they would have been swept away when deleting orphan media files.
**This task should only be run once**, and will be removed in version 1.2.0 of Mobilizon.
```bash
mix mobilizon.maintenance.fix_unattached_media_in_body
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl maintenance.fix_unattached_media_in_body
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl maintenance.fix_unattached_media_in_body
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.maintenance.fix_unattached_media_in_body
```
# Manage actors
## List all available commands
!!! tip "Environment"
You need to run these commands with the appropriate environment loaded, so probably prefix with `MIX_ENV=prod`.
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl actors
```
## List all available commands
```bash
mix mobilizon.actors
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl actors
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.actors
```
## Show an actors details
```bash
mix mobilizon.actors.show
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl actors.show <actor_username>
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl actors.show <actor_username>
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.actors.show <actor_username>
```
Where `<actor_username>` is a local or federated, profile or group, such as `myprofile`, `mygroup`, `remote_profile@remote_instance.com` or `mygroup@my_remote_instance.com`.
In addition to basic informations, it also tells which user the profile belongs to, if local.
## Refresh a remote actor
Can be helpful in case of federation issues.
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl actors.refresh <federated_group_name>
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl actors.refresh <federated_group_name>
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.actors.refresh <federated_group_name>
```
In addition to basic informations, it also tells which user the profile belongs to, if local.
\ No newline at end of file
Where `<federated_group_name>` is a federated group name like `mygroup@my_remote_instance.com`.
\ 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
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users
```
## List all available commands
```bash
mix mobilizon.users
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl users
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.users
```
## Create a new user
```bash
mix mobilizon.users.new <email> [<options>]
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users.new <email> [<options>]
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl users.new <email> [<options>]
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.users.new <email> [<options>]
```
### Options
......@@ -25,15 +45,37 @@ mix mobilizon.users.new <email> [<options>]
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>
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users.show <email>
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl users.show <email>
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.users.show <email>
```
## Modify an user
```bash
mix mobilizon.users.modify <email>
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users.modify <email> [<options>]
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl users.modify <email> [<options>]
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.users.modify <email> [<options>]
```
### Options
......@@ -47,10 +89,20 @@ mix mobilizon.users.modify <email>
## Delete an user
```bash
mix mobilizon.users.delete <email>
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users.delete <email> [<options>]
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl users.delete <email> [<options>]
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.users.delete <email> [<options>]
```
### Options
* `--assume_yes`/`-y` Don't ask for confirmation
......@@ -63,10 +115,20 @@ mix mobilizon.users.delete <email>
Manually run the cleaning of unconfirmed users (and their profiles).
```bash
mix mobilizon.users.clean [<options>]
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl users.clean [<options>]
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl users.clean [<options>]
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.users.clean [<options>]
```
### Options
* `-v`, `--verbose` List the users that were deleted. Implied when using `--dry-run`.
* `-d`, `--days` The number of days after which an unconfirmed user is selected to be deleted
......
......@@ -6,9 +6,21 @@
Manually run the cleaning of orphan media files.
```bash
mix mobilizon.media.clean_orphan [<options>]
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl media.clean_orphan [<options>]
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl media.clean_orphan [<options>]
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.media.clean_orphan [<options>]
```
### Options
* `-v`, `--verbose` List the files that were deleted. Implied when using `--dry-run`.
......
......@@ -2,40 +2,100 @@
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>
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl relay.follow <relay_host>
```
Example:
```bash
sudo -u mobilizon ./bin/mobilizon_ctl relay.follow example.org
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl relay.follow <relay_host>
```
Example:
```bash
docker-compose exec mobilizon mobilizon_ctl relay.follow example.org
```
Example:
```bash
mix mobilizon.relay.follow example.org
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.relay.follow <relay_host>
```
Example:
```bash
MIX_ENV=prod mix mobilizon.relay.follow example.org
```
## Make your instance unfollow a mobilizon instance
```bash
mix mobilizon.relay.unfollow <relay_host>
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl relay.unfollow <relay_host>
```
Example:
```bash
sudo -u mobilizon ./bin/mobilizon_ctl relay.unfollow example.org
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl relay.unfollow <relay_host>
```
Example:
```bash
mix mobilizon.relay.unfollow example.org
```
Example:
```bash
docker-compose exec mobilizon mobilizon_ctl relay.unfollow example.org
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.relay.unfollow <relay_host>
```
Example:
```bash
MIX_ENV=prod mix mobilizon.relay.unfollow example.org
```
## Make your instance refresh a mobilizon instance
It will crawl public events from the remote instance public outbox.
```bash
mix mobilizon.relay.refresh <relay_host>
```
=== "Release"
```bash
sudo -u mobilizon ./bin/mobilizon_ctl relay.refresh <relay_host>
```
Example:
```bash
sudo -u mobilizon ./bin/mobilizon_ctl relay.refresh example.org
```
=== "Docker"
```bash
docker-compose exec mobilizon mobilizon_ctl relay.refresh <relay_host>
```
Example:
```bash
docker-compose exec mobilizon mobilizon_ctl relay.refresh example.org
```
=== "Source"
```bash
MIX_ENV=prod mix mobilizon.relay.refresh <relay_host>
```
Example:
```bash
mix mobilizon.relay.refresh example.org
```
Example:
```bash
MIX_ENV=prod mix mobilizon.relay.refresh example.org
```
# Configuration
Basic Mobilizon configuration can be handled through the Admin panel in the UI.
Otherwise you need to edit various configuration files, depending on how you installed Mobilizon.
Core mobilizon configuration must be managed into the `config/prod.secret.exs` file.
## Releases
Core mobilizon configuration must be managed into the `/etc/mobilizon/config.exs` file.
After performing changes to this file, you have to restart the Mobilizon service:
```
systemctl restart mobilizon
```
## Docker
Basic things can be edited through the `.env` file, but [you can use the `config.exs` file](../docker.md#advanced-configuration) linked to a volume to edit & add custom settings.
## Source
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
......
# 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 file
```
### 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`.
### 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 Ubuntu/Debian on [this page](https://elixir-lang.org/install.html#unix-and-unix-like) to add Erlang Solutions repo and install Erlang and Elixir.
!!! tip
The Erlang package also wants to install an add-on for Emacs for some reason (but it doesn't install Emacs). If you see a warning, nothing to worry about.
### PostgreSQL and PostGIS
Mobilizon uses the [PostgreSQL](https://www.postgresql.org) database, and the PostgreSQL [Postgis](https://postgis.net) extension to store geographical data into PostgreSQL.
```bash
sudo apt install postgresql postgresql-contrib
sudo apt install --install-recommends postgis
```
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.
```bash
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.
```bash
sudo apt install gifsicle jpegoptim optipng pngquant
```
Once finished, let's [head back to the install guide](index.md).
## Arch Linux
Run the following command to install all at once:
```bash
sudo pacman -S nodejs postgresql openssl git wget unzip base-devel yarn 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](index.md).
## Other distributions
Feel free to update this file in a merge request!
......@@ -37,7 +37,7 @@ Not really. Being written in Elixir, Mobilizon doesn't need much resources once
Some Mobilizon dependencies require system tools or libraries to compile (such as `cmake` or `gcc`). You might be missing a system dependency.
Check the [dependency guide](./dependencies.md) (especially the "Basic tools" section), make sure everything is installed and clean and recompile Mobilizon's dependencies with:
Check the [source install guide](./install/source.md) (especially the "Basic tools" section), make sure everything is installed and clean and recompile Mobilizon's dependencies with:
```
MIX_ENV=prod mix deps.clean --all
......@@ -47,7 +47,7 @@ MIX_ENV=prod mix compile