Merge remote-tracking branch 'upstream/frontv2' into frontv2

19 files changed, 885 insertions, 30 deletions

diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico
new file mode 100644
index 00000000..e1c8dfd4
--- /dev/null
+++ b/docs/_static/favicon.ico
diff --git a/docs/_static/img/logo.svg b/docs/_static/img/logo.svg
new file mode 100644
index 00000000..7bd8af6a
--- /dev/null
+++ b/docs/_static/img/logo.svg
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="64px" height="64px" viewBox="0 0 64 64" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 56.3 (81716) - https://sketch.com -->
+    <title>navbar / logged in</title>
+    <desc>Created with Sketch.</desc>
+    <g id="Symbols" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="navbar-/-logged-in" fill-rule="nonzero">
+            <g id="Logo">
+                <polygon id="tape-2" fill="#C728B6" points="52.0120916 40 55.619713 40 40 50.4045133 40 48.0014253 52.0120916 40"></polygon>
+                <path d="M8.85477443,40.3198496 C10.7035505,41.2441327 12.7563208,41.8209238 14.927485,41.9646225 L24,48.0129658 L24,50.4166667 L8.85477443,40.3198496 L8.85477443,40.3198496 Z" id="tape-1" fill="#C728B6"></path>
+                <path d="M38.3333333,12 L61.6666667,12 C62.9553311,12 64,13.0446689 64,14.3333333 L64,37.6666667 C64,38.9553311 62.9553311,40 61.6666667,40 L38.3333333,40 C37.0446689,40 36,38.9553311 36,37.6666667 L36,14.3333333 C36,13.0446689 37.0446689,12 38.3333333,12 Z M56.75,26 L45,18 L45,34 L56.75,26 Z" id="Play" fill="#313DF2"></path>
+                <path d="M4.34513171,28.8690263 L8.95520669,29.7910413 C7.63820189,27.3468948 7.7225468,24.5032024 8.95388851,22.2092223 L4.34513171,23.1309737 C4.11960331,24.0502625 4,25.0111638 4,26 C4,26.9888362 4.11960331,27.9497375 4.34513265,28.8690266 L4.34513171,28.8690263 Z M19.3430094,14.4718188 L16.240146,18.0024996 C18.8424619,18.0831165 21.3473441,19.4319178 22.8055348,21.7945507 L24.3110973,17.3440175 C22.9301734,16.0177787 21.2325726,15.0188077 19.3430094,14.4718188 Z M24.3110973,34.6559825 L22.806151,30.207271 C22.1331915,31.2980641 21.1877888,32.242433 20,32.9282032 C18.8122112,33.6139734 17.5216623,33.9605317 16.240528,33.9979351 L19.3430094,37.5281812 C21.2325726,36.9811923 22.9301734,35.9822213 24.3110973,34.6559825 L24.3110973,34.6559825 Z M12.0019223,26.0003361 C12.0019223,28.2091063 13.7924843,29.9996684 16.0012545,29.9996684 C18.2100247,29.9996684 20.0005867,28.2091063 20.0005867,26.0003361 C20.0005867,23.791566 18.2100247,22.0010039 16.0012545,22.0010039 C13.7924843,22.0010039 12.0019223,23.791566 12.0019223,26.0003361 Z M16,42 C7.163444,42 0,34.836556 0,26 C0,17.163444 7.163444,10 16,10 C24.836556,10 32,17.163444 32,26 C32,34.836556 24.836556,42 16,42 Z" id="Reel" fill="#313DF2"></path>
+                <path d="M26,44 L38,44 C39.1045695,44 40,44.8954305 40,46 L40,50.75 L38,52 L26,52 L24,50.75 L24,46 C24,44.8954305 24.8954305,44 26,44 Z" id="head" fill="#313DF2"></path>
+            </g>
+        </g>
+    </g>
+</svg>
\ No newline at end of file
diff --git a/docs/admin/index.rst b/docs/admin/index.rst
new file mode 100644
index 00000000..0200cf03
--- /dev/null
+++ b/docs/admin/index.rst
@@ -0,0 +1,35 @@
+Administrator Documentation
+===========================
+
+This documentation is targeted at administrators of instances. This tipically refers to
+the person(s) responsible for running the server and managing the software on a technical
+level.
+
+Setup Guides
+------------
+
+.. toctree::
+    :maxdepth: 2
+
+    ../installation/index
+    configuration
+    storage
+
+Administration
+--------------
+
+.. toctree::
+    :maxdepth: 2
+
+    flask
+    commands
+    url
+    upgrading
+
+Troubleshooting Issues
+----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   troubleshooting
diff --git a/docs/admin/upgrading.rst b/docs/admin/upgrading.rst
new file mode 100644
index 00000000..88bc834e
--- /dev/null
+++ b/docs/admin/upgrading.rst
@@ -0,0 +1,65 @@
+Upgrading your reel2bits instance to a newer version
+====================================================
+
+.. note::
+
+    Before upgrading your instance, we strongly advise you to make at last a database backup.
+    Ideally, you should make a full backup, including the database and the media files.
+
+    We're commited to make upgrade as easy and straightforward as possible,
+    however, reel2bits is still in development and you'll be safer with a backup.
+
+Non-docker setup
+----------------
+
+Upgrading the backend
+^^^^^^^^^^^^^^^^^^^^^
+
+On non-docker, upgrade involves a few more commands. We assume your setup
+match what is described in :doc:`/installation/linux`:
+
+.. important::
+
+    Further commands involving python should always be run after you activated
+    the virtualenv, as described earlier, otherwise those commands will raise
+    errors
+
+Locate the latest release `from the release page <https://github.com/rhaamo/reel2bits/releases>`_ like ``v0.6``, or if you want to run the unstable ``master`` branch.
+
+.. parsed-literal::
+
+    sudo -u reel2bits -H bash
+    cd /home/reel2bits/reel2bits/
+    # If upgrading from stable releases
+    git fetch -a
+    git checkout v0.6
+    # Or if using master:
+    git pull
+
+    # Update dependencies
+    source /home/reel2bits/virtualenv/bin/activate
+    pip install -r requirements.txt
+
+Then exit your reel2bits user and run as root:
+
+.. parsed-literal::
+
+    sudo systemctl stop reel2bits.target
+
+Then apply databases migrations:
+
+.. parsed-literal::
+
+    sudo -u reel2bits -H bash
+    cd /home/reel2bits/reel2bits/
+    source /home/reel2bits/virtualenv/bin/activate
+    flask db upgrade
+
+You have to update the front-end too, see :ref:`front-installation <front-installation>`.
+
+Exit and restart services:
+
+.. parsed-literal::
+
+    sudo systemctl start reel2bits.target
+
diff --git a/docs/build_docs.sh b/docs/build_docs.sh
new file mode 100755
index 00000000..3b2973a2
--- /dev/null
+++ b/docs/build_docs.sh
@@ -0,0 +1,2 @@
+#!/bin/bash -eux
+python -m sphinx . $BUILD_PATH
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000..fe99abd7
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# reel2bits documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import datetime
+
+sys.path.insert(0, os.path.abspath("../"))
+
+import version as reel2bits_version  # NOQA
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.graphviz"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+year = datetime.datetime.now().year
+project = "reel2bits"
+copyright = "{}, Dashie".format(year)
+author = "Dashie"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = reel2bits_version.VERSION
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "guillotina"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "reel2bitsdoc"
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [(master_doc, "reel2bits.tex", "reel2bits Documentation", "Dashie", "manual")]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "reel2bits", "reel2bits Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "reel2bits",
+        "reel2bits Documentation",
+        author,
+        "reel2bits",
+        "One line description of project.",
+        "Miscellaneous",
+    )
+]
+
+# -- Build legacy redirect files -------------------------------------------
+
+# Define list of redirect files to be build in the Sphinx build process
+
+redirect_files = [
+    # ('foo.html', 'foo/bar.html'),
+]
+
+# Generate redirect template
+
+redirect_template = """\
+<html>
+  <head>
+    <meta http-equiv="refresh" content="1; url={new}" />
+    <script>
+      window.location.href = "{new}"
+    </script>
+  </head>
+</html>
+"""
+
+
+# Tell Sphinx to copy the files
+
+
+def copy_legacy_redirects(app, docname):
+    if app.builder.name == "html":
+        for html_src_path, new in redirect_files:
+            page = redirect_template.format(new=new)
+            target_path = app.outdir + "/" + html_src_path
+            if not os.path.exists(os.path.dirname(target_path)):
+                os.makedirs(os.path.dirname(target_path))
+            with open(target_path, "w") as f:
+                f.write(page)
+
+
+def setup(app):
+    import sphinx_guillotina_theme
+
+    sphinx_guillotina_theme.setup(app)
+    app.connect("build-finished", copy_legacy_redirects)
diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 00000000..3bdd7dc2
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst
\ No newline at end of file
diff --git a/docs/features.rst b/docs/features.rst
new file mode 100644
index 00000000..3786b0a8
--- /dev/null
+++ b/docs/features.rst
@@ -0,0 +1,31 @@
+Features
+========
+
+Scope
+-----
+
+reel2bits is an application designed to allow users to share content they create, it can be music albums, tracks or your own podcast.
+
+Structure
+---------
+
+The project is split in two parts:
+
+1. The backend a REST API developed using Python3 and Flask.
+2. The frontend, that consumes the API, built as a single page application with VueJS.
+
+While the main interface to the server and API is the bundled front-end, the project itself is agnostic in the way you connect to it.
+Therefore, desktop clients or apps could be developed and could implement the same (or more) features as the bundled frontend.
+
+This modularity also makes it possible to deploy only a single component from the system.
+
+The backend shares some APIs used by Mastodon, so app development can be simplified a bit.
+
+Federation
+----------
+
+Each reel2bits instance is able to federate its user profiles and Tracks with projects such as Mastodon or Pleroma.
+Albums does not yet federates and will only federate with another reel2bits instance.
+
+Another user using Mastodon or Pleroma can successfully follow a reel2bits user, and receive new tracks notifications as
+soon as they are processed and available.
diff --git a/docs/payloads/audio.json b/docs/federation/audio.json
index dba53995..dba53995 100644
--- a/docs/payloads/audio.json
+++ b/docs/federation/audio.json
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000..a0f9501b
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,24 @@
+.. reel2bits documentation master file
+
+reel2bits documentation
+=========================
+
+reel2bits is a self-hosted, free and open-source web application dedicated for sharing your own music tracks, albums, or podcasts.
+
+.. toctree::
+    :maxdepth: 2
+
+    features
+    users/index
+    admin/index
+    developers/index
+    documentation/index
+    contributing
+    translators
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/installation/external_dependencies.rst b/docs/installation/external_dependencies.rst
new file mode 100644
index 00000000..83d2437e
--- /dev/null
+++ b/docs/installation/external_dependencies.rst
@@ -0,0 +1,76 @@
+External dependencies
+=====================
+
+Database setup (PostgreSQL)
+---------------------------
+
+reel2bits requires a PostgreSQL database to work properly. Please refer
+to the `PostgreSQL documentation <https://www.postgresql.org/download/>`_
+for installation instructions specific to your os.
+
+On Debian-like systems, you would install the database server like this:
+
+.. code-block:: shell
+
+    sudo apt-get install postgresql postgresql-contrib
+
+The remaining steps are heavily inspired from `this Digital Ocean guide <https://www.digitalocean.com/community/tutorials/how-to-set-up-django-with-postgres-nginx-and-gunicorn-on-ubuntu-16-04>`_.
+
+Open a database shell:
+
+.. code-block:: shell
+
+    sudo -u postgres psql
+
+Create the project database and user:
+
+.. code-block:: shell
+
+    CREATE DATABASE "reel2bits"
+      WITH ENCODING 'utf8';
+    CREATE USER reel2bits;
+    GRANT ALL PRIVILEGES ON DATABASE reel2bits TO reel2bits;
+
+.. warning::
+
+    It's important that you use utf-8 encoding for your database,
+    otherwise you'll end up with errors and crashes later on when dealing
+    with music metadata that contains non-ascii chars.
+
+Assuming you already have :ref:`created your reel2bits user <create-reel2bits-user>`,
+you should now be able to open a postgresql shell:
+
+.. code-block:: shell
+
+    sudo -u reel2bits -H psql
+
+Unless you give a superuser access to the database user, you should also
+enable some extensions on your database server, as those are required
+for reel2bits to work properly:
+
+.. code-block:: shell
+
+    sudo -u postgres psql reel2bits -c 'CREATE EXTENSION "uuid-ossp";'
+
+Cache setup (Redis)
+-------------------
+
+reel2bits also requires a cache server:
+
+- To handle asynchronous tasks such as music transcoding or some ActivityPub tasks
+
+On Debian-like distributions, a redis package is available, and you can
+install it:
+
+.. code-block:: shell
+
+    sudo apt-get install redis-server
+
+This should be enough to have your redis server set up.
+
+audiowaveform tool
+------------------
+
+We needs the `audiowaveform tool <https://github.com/bbc/audiowaveform>`_ which is used to precompute the audio waveforms used by the players.
+
+The best way to install it is to `follow the official documentation <https://github.com/bbc/audiowaveform#installation>`_ which already mention how to install on Ubuntu or build from sources.
diff --git a/docs/installation/index.rst b/docs/installation/index.rst
new file mode 100644
index 00000000..5d01a8c3
--- /dev/null
+++ b/docs/installation/index.rst
@@ -0,0 +1,132 @@
+Installation
+============
+
+Project architecture
+--------------------
+
+The project relies on the following components and services to work:
+
+- A web application server (Python/Flask/Waitress)
+- A PostgreSQL database to store application data
+- A redis server to store tasks data
+- A celery worker to run asynchronous tasks (such as transcoding or ActivityPub)
+- A `ntp-synced clock <https://wiki.debian.org/NTP>`_ to ensure federation is working seamlessly
+
+.. note::
+
+    The synced clock is needed for federation purpose, to assess
+    the validity of incoming requests.
+
+Software requirements
+---------------------
+
+A mostly up-to date OS, with a Python >= 3.6, and a reverse proxy such as Nginx.
+
+Available installation methods
+-------------------------------
+
+Docker will soon be available to deploy a reel2bits instance.
+Right now you can install it on any Linux distribution.
+
+.. toctree::
+    :maxdepth: 1
+
+    external_dependencies
+    linux
+    systemd
+
+reel2bits packages are available for the following platforms:
+
+- `YunoHost 3 <https://yunohost.org/>`_: https://github.com/YunoHost-Apps/reel2bits_ynh
+
+Running reel2bits on the master branch
+---------------------------------------
+
+Traditional deployments are done using tagged releases. However, you
+may want to benefits from the latest change available, or the help detect
+bugs before they are included in actual releases.
+
+To do that, you'll need to run your instance on the master branch,
+which contains all the unreleased changes and features of the next version.
+
+Please take into account that the master branch
+may be unstable and will contain bugs that may affect the well being of your
+instance. If you are comfortable with that, you need to backup at least your database
+before pulling latest changes from the master branch.
+
+Otherwise, the deployment process is similar to deploying with releases.
+
+.. _reverse-proxy-setup:
+
+Reverse proxy
+--------------
+
+In order to make reel2bits accessible from outside your server and to play nicely with other applications on your machine, you should configure a reverse proxy.
+
+Nginx
+^^^^^
+
+Ensure you have a recent version of nginx on your server. On Debian-like system, you would have to run the following:
+
+.. code-block:: bash
+
+    sudo apt-get update
+    sudo apt-get install nginx
+
+You can now copy the shipped nginx config:
+
+.. code-block:: bash
+
+    cp /home/reel2bits/reel2bits/deploy/reel2bits.nginx /etc/nginx/sites-available/reel2bits.conf
+    ln -s /etc/nginx/sites-available/reel2bits.conf /etc/nginx/sites-enabled/
+
+Don't forget to edit ```/etc/nginx/sites-enabled/reel2bits.conf`` to suit your needs.
+
+HTTPS Configuration
+:::::::::::::::::::
+
+At this point you will need a SSL certificate to enable HTTPS on your server.
+The default nginx configuration assumes you have those available at ``/etc/letsencrypt/live/${REEL2BITS_HOSTNAME}/``, which
+is the path used by `certbot <https://certbot.eff.org/docs/>`_ when generating certificates with Let's Encrypt.
+
+In you already have a certificate you'd like to use, simply update the nginx configuration
+and replace ``ssl_certificate`` and ``ssl_certificate_key`` values with the proper paths.
+
+If you don't have one, comment or remove the lines starting with ``ssl_certificate`` and ``ssl_certificate_key``. You can then proceed to generate
+a certificate, as shown below:
+
+.. code-block:: shell
+
+    # install certbot with nginx support
+    sudo apt install python-certbot-nginx
+    # generate the certificate
+    # (accept the terms of service if prompted)
+    sudo certbot --nginx -d yourreel2bits.domain
+
+This should create a valid certificate and edit the nginx configuration to use the new certificate.
+
+Reloading
+:::::::::
+
+Check the configuration is valid with ``nginx -t`` then reload your nginx server with ``sudo systemctl reload nginx``.
+
+About internal locations
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Music (and other static) files are never served by the app itself, but by the reverse
+proxy. This is needed because a webserver is way more efficient at serving
+files than a Python process.
+
+However, we do want to ensure users have the right to access music files, and
+it can't be done at the proxy's level. To tackle this issue, `we use
+nginx's internal directive <http://nginx.org/en/docs/http/ngx_http_core_module.html#internal>`_.
+
+When the API receives a request on its music serving endpoint, it will check
+that the user making the request can access the file. Then, it will return an empty
+response with a ``X-Accel-Redirect`` header. This header will contain the path
+to the file to serve to the user, and will be picked by nginx, but never sent
+back to the client.
+
+Using this technique, we can ensure music files are covered by the authentication
+and permission policy of your instance, while keeping as much as performance
+as possible.
diff --git a/docs/installation/linux.rst b/docs/installation/linux.rst
new file mode 100644
index 00000000..3f41dfa9
--- /dev/null
+++ b/docs/installation/linux.rst
@@ -0,0 +1,228 @@
+Debian based distribution installation
+======================================
+
+.. note::
+
+    This guide targets Debian 9 (Stretch), which is the latest Debian, or the latest ubuntu
+
+External dependencies
+---------------------
+
+The guides will focus on installing reel2bits-specific components and
+dependencies. However, reel2bits requires a
+:doc:`few external dependencies <./external_dependencies>` for which
+documentation is outside of this document scope.
+
+Install system dependencies
+---------------------------
+
+On Debian-like systems, you can install them using:
+
+.. code-block:: shell
+
+    sudo apt-get update
+    # Install dependencies
+    sudo apt-get install python3-pip python3-venv git
+    # reel2bits dependencies
+    sudo apt install build-essential sox ffmpeg libavcodec-extra libjpeg-dev libmagic-dev libpq-dev postgresql-client python3-dev make libtag1v5 libmagic1 libffi6 libsox-dev libsox-fmt-all libtag1-dev libmagic-dev libffi-dev libgd-dev libmad0-dev libsndfile1-dev libid3tag0-dev libmediainfo-dev
+
+Layout
+------
+
+All reel2bits-related files will be located under ``/home/reel2bits`` apart
+from database files and a few configuration files. We will also have a
+dedicated ``reel2bits`` user to launch the processes we need and own those files.
+
+You are free to use different values here, just remember to adapt those in the
+next steps.
+
+.. _create-reel2bits-user:
+
+Create the user and the directory:
+
+.. code-block:: shell
+
+    sudo useradd -r -s /usr/sbin/nologin -d /home/reel2bits -m reel2bits
+    cd /home/reel2bits
+
+Log in as the newly created user from now on:
+
+.. code-block:: shell
+
+    sudo -u reel2bits -H bash
+
+
+Download latest reel2bits release
+---------------------------------
+
+Locate the latest release `from the release page <https://github.com/rhaamo/reel2bits/releases>`_ like ``v0.5``, or if you want to run the unstable ``master`` branch.
+
+Still under your ``reel2bits`` user:
+
+.. code-block:: shell
+
+    # if release:
+    git checkout -b v0.5 https://github.com/rhaamo/reel2bits/
+    # Or master
+    git checkout https://github.com/rhaamo/reel2bits/
+
+Python dependencies
+--------------------
+
+Go to the project directory:
+
+.. code-block:: shell
+
+    cd reel2bits
+
+To avoid collisions with other software on your system, Python dependencies
+will be installed in a dedicated
+`virtualenv <https://docs.python.org/3/library/venv.html>`_.
+
+First, create the virtualenv:
+
+.. code-block:: shell
+
+    python3 -m venv /home/reel2bits/virtualenv
+
+This will result in a ``virtualenv`` directory being created in
+``/home/reel2bits/virtualenv``.
+
+In the rest of this guide, we'll need to activate this environment to ensure
+dependencies are installed within it, and not directly on your host system.
+
+This is done with the following command:
+
+.. code-block:: shell
+
+    source /home/reel2bits/virtualenv/bin/activate
+
+Finally, install the python dependencies:
+
+.. code-block:: shell
+
+    pip install wheel
+    pip install waitress
+    pip install -r requirements.txt
+
+.. important::
+
+    Further commands involving python should always be run after you activated
+    the virtualenv, as described earlier, otherwise those commands will raise
+    errors
+
+Configuration file
+------------------
+
+You can now start to configure reel2bits:
+
+.. code-block:: shell
+
+    cp config.py.sample config.py
+
+Then edit this file as you wishes.
+
+Sentry
+------
+
+If you known, and use Sentry, you can install the python package:
+
+.. code-block:: shell
+
+    pip install sentry-sdk[flask]
+
+And setup your DSN in ``config.py``.
+
+Database setup
+---------------
+
+You should now be able to import the initial database structure:
+
+.. code-block:: shell
+
+    flask db upgrade
+
+This will create the required tables and rows.
+
+.. note::
+
+    You can safely execute this command any time you want, this will only
+    run unapplied migrations.
+
+Then populate the database with default values (seeds):
+
+.. code-block:: shell
+
+    flask seed
+
+
+Create an admin account
+-----------------------
+
+You can then create your first user account:
+
+.. code-block:: shell
+
+    flask createuser
+
+.. important::
+
+    If you don't create an user, the first one to register from the web interface will be administrator !
+
+.. _front-installation:
+
+Front installation
+------------------
+
+You also needs to either get a frontend prebuild or build it yourself.
+
+Pre-build
+^^^^^^^^^
+
+- The URL for a stable release will be `https://assets.reel2bits.org/front-dist-master-v0.5.zip`.
+- The URL for master will be `https://assets.reel2bits.org/front-dist-master-.zip`.
+
+You can always go to https://assets.reel2bits.org/ to check the available archives, and test the link before downloading it.
+
+Get the archive and extract:
+
+.. code-block:: shell
+
+    sudo -u reel2bits -H bash
+    cd
+    wget <the URL defined earlier>
+    # use the stable or master name you got earlier too
+    unzip "front-dist-master-v0.5.zip" -d extract
+    # beware with this command, take care
+    rm -rf "reel2bits/front/dist/*"
+    cp -r extract/dist/* reel2bits/front/dist/
+    # same with this one
+    rm -rf "extract"
+
+.. important::
+
+    Any update to the frontend files needs either a restart of the `reel2bits-web` service, or wait until the file cache expires.
+
+Build it yourself
+^^^^^^^^^^^^^^^^^
+
+Makes sure you have nodejs installed then:
+
+.. code-block:: shell
+
+    sudo -u reel2bits -H bash
+    cd reel2bits/front
+    yarn
+    npm run build
+
+That's it.
+
+Systemd unit file
+------------------
+
+See :doc:`./systemd`.
+
+Reverse proxy setup
+--------------------
+
+See :ref:`reverse-proxy <reverse-proxy-setup>`.
diff --git a/docs/installation/systemd.rst b/docs/installation/systemd.rst
new file mode 100644
index 00000000..add615c9
--- /dev/null
+++ b/docs/installation/systemd.rst
@@ -0,0 +1,45 @@
+Systemd configuration
+----------------------
+
+.. note::
+
+    All the command lines below should be executed as root.
+
+Systemd offers a convenient way to manage your reel2bits instance if you're
+not using docker.
+
+We'll see how to setup systemd to properly start a reel2bits in