diff --git a/docs/administrator_documentation/index.md b/docs/administrator_documentation/index.md new file mode 100644 index 000000000..59db87073 --- /dev/null +++ b/docs/administrator_documentation/index.md @@ -0,0 +1 @@ +# Get started diff --git a/docs/administrator_documentation/installation_docs/debian/create_user.md b/docs/administrator_documentation/installation_docs/debian/create_user.md new file mode 100644 index 000000000..cd51037dd --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/create_user.md @@ -0,0 +1,23 @@ +# 2. Create a Funkwhale user + +It's good practice to create a user on your server for Funkwhale administration. Doing this makes it easy to make sure you're running commands from the right place. Follow these steps to set up your user. + +1. Create the `funkwhale` user and set its shell to `bash` and its home directory to `/srv/funkwhale`. + + ```{code} bash + sudo useradd -r -s /usr/bin/bash -d /srv/funkwhale -m funkwhale + ``` + +2. Create a password for the user. You need to do this so that you can use this user to perform database administration. + + ```{code} bash + sudo passwd funkwhale + ``` + +3. Finally, give the user `sudo` privileges. You need to do this so that the user can run administrative tasks. + + ```{code} + usermod -aG sudo funkwhale + ``` + +That's it! You've created your `funkwhale` user. Log in as this user when you want to perform any Funkwhale related tasks. diff --git a/docs/administrator_documentation/installation_docs/debian/database.md b/docs/administrator_documentation/installation_docs/debian/database.md new file mode 100644 index 000000000..f539541af --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/database.md @@ -0,0 +1,60 @@ +# 6. Set up your database + +Funkwhale uses a [PostgreSQL](https://www.postgresql.org/) database to store information. Follow these steps to set up your database. + +1. Install PostgreSQL and the `postgresql-contrib` package. This package contains extra features that Funkwhale uses. + + ```{code} bash + sudo apt-get install postgresql postgresql-contrib + ``` + +2. Once you've installed PostgreSQL, launch a `psql` shell as the `postgres` user to set up your database. + + ```{code} bash + sudo -u postgres psql + ``` + +3. Create your Funkwhale database. + + ```{code} psql + CREATE DATABASE funkwhale WITH ENCODING 'utf8'; + ``` + +4. Create a user for Funkwhale. This user needs all privileges so it can manage the database. + + ```{code} psql + CREATE USER funkwhale; + GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale; + ``` + +5. Once you're finished, exit the shell + + ```{code} psql + exit + ``` + +6. Run the following commands to create extra extensions for the `funkwhale` database. + + ```{code} bash + sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "unaccent";' + sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "citext";' + ``` + +7. Your database is ready to be populated! Use the `manage.py` script to create the database structure. + + ```{code} bash + cd /srv/funkwhale/api + poetry run python manage.py migrate + ``` + +````{note} +You may see the following warning when applying migrations: + +```{code} +"Your models have changes that are not yet reflected in a migration, and so won't be applied." +``` + +You can safely ignore this warning. +```` + +That's it! You've finished setting up your database. diff --git a/docs/administrator_documentation/installation_docs/debian/download_funkwhale.md b/docs/administrator_documentation/installation_docs/debian/download_funkwhale.md new file mode 100644 index 000000000..b43ffb692 --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/download_funkwhale.md @@ -0,0 +1,59 @@ +# 3. Download Funkwhale + +Once you've created your `funkwhale` user you can download the Funkwhale software itself. + +```{contents} +:local: +``` + +## Create the directory layout + +1. Log in to your `funkwhale` account. This user works in the `/srv/funkwhale` directory. + + ```{code} bash + su funkwhale + ``` + +2. Create the directories for Funkwhale. + + ```{code} bash + mkdir -p config api data/static data/media data/music front + ``` + +That's it! Your directory structure should look like this: + +```{code} +. +├── config # config / environment files +├── api # the Funkwhale API +├── data # files served by the API + └── static # storage location for persistent data + └── media # storage location for media files + └── music # storage location for audio files +└── front # frontend files for the user interface +``` + +## Download the Funkwhale release + +Once you've created the directory structure you can download Funkwhale. Funkwhale comes in two parts: the API and the Frontend. You need both to run the application. + +1. Download the API. + + ```{code} bash + curl -L -o "api-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_api" + unzip "api-$FUNKWHALE_VERSION.zip" -d extracted + mv extracted/api/* api/ + rm -rf extracted rm api-$FUNKWHALE_VERSION.zip + ``` + +2. Download the frontend + + ```{code} bash + curl -L -o "front-$FUNKWHALE_VERSION.zip" "https://dev.funkwhale.audio/funkwhale/funkwhale/-/jobs/artifacts/$FUNKWHALE_VERSION/download?job=build_front" + unzip "front-$FUNKWHALE_VERSION.zip" -d extracted + mv extracted/front . + rm -rf extracted + rm front-$FUNKWHALE_VERSION.zip + ``` + +You're done! These commands put the software in the correct location for Funkwhale to serve them. diff --git a/docs/administrator_documentation/installation_docs/debian/env_file.md b/docs/administrator_documentation/installation_docs/debian/env_file.md new file mode 100644 index 000000000..20b3cfb97 --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/env_file.md @@ -0,0 +1,47 @@ +# 5. Set up your environment file + +The environment file contains options you can use to control your Funkwhale pod. Follow these steps to get a working environment up and running. + +1. Download the `.env` file to your `/srv/funkwhale/config` directory. + + ```{code} bash + curl -L -o /srv/funkwhale/config/.env "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/env.prod.sample" + ``` + +2. Generate a secret key for Django. This keeps your Funkwhale data secure. Do not share this key with anybody. + + ```{code} bash + openssl rand -base64 45 + ``` + +3. Reduce the permissions on your `.env` file to `600`. This means that only the `funkwhale` user can read and write this file. + + ```{code} bash + chmod 600 /srv/funkwhale/config/.env + ``` + +4. Open the `.env` file in a text editor. For this example, we will use `nano`. + + ```{code} bash + nano /srv/funkwhale/config/.env + ``` + +5. Update the following settings: + - Paste the seccret key in the `DJANGO_SECRET_KEY` field. + - Populate the `DATABASE_URL` field: + + ```{code} + DATABASE_URL=postgresql://funkwhale@:5432/funkwhale + ``` + + - Populate the `CACHE_URL` field: + + ```{code} + CACHE_URL=redis://127.0.0.1:6379/0 + ``` + + - Populate the `FUNKWHALE_HOSTNAME` field with the URL of your server. + +6. Hit {kbd}`ctrl + x` then {kbd}`y` to save the file and close `nano`. + +You're done! Your environment file is now ready to go. You can check out a full list of configuration options in our Environment file guide. diff --git a/docs/administrator_documentation/installation_docs/debian/funkwhale_dependencies.md b/docs/administrator_documentation/installation_docs/debian/funkwhale_dependencies.md new file mode 100644 index 000000000..9ac33f5d5 --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/funkwhale_dependencies.md @@ -0,0 +1,23 @@ +# 1. Install Funkwhale dependencies + +To install Funkwhale on your server, you first need to install its dependencies. We provide all dependencies in a single file to enable you to install everything at once. + +## Before you begin + +Set a `FUNKWHALE_VERSION` variable to the version you want to install. You will use this version for all commands in this guide. + +```{code} bash +export FUNKWHALE_VERSION=1.2.1 +``` + +## Install Funkwhale dependencies + +To install all Funkwhale dependencies, you need to download the dependencies file. You can pass the information from this file to `apt` using the following command: + +```{code} bash +sudo apt install $(curl https://dev.funkwhale.audio/funkwhale/funkwhale/-/raw/$FUNKWHALE_VERSION/api/requirements.apt) +``` + +When prompted, hit {kbd}`y` to confirm the install. + +That's it! `apt` installs all dependencies and tells you once it has finished. diff --git a/docs/administrator_documentation/installation_docs/debian/funkwhale_setup.md b/docs/administrator_documentation/installation_docs/debian/funkwhale_setup.md new file mode 100644 index 000000000..868a42bcb --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/funkwhale_setup.md @@ -0,0 +1,29 @@ +# 7. Set up Funkwhale + +Once you have got your database up and running, you can get Funkwhale ready to launch. Use the built-in `manage.py` script to get things ready. + +```{contents} +:local: +``` + +## Create a superuser for your pod + +```{note} +You can create several superusers. +``` + +To start using Funkwhale, you need to create a superuser for your pod. This user has all the permissions needed to administrate the pod. Follow these steps to create a superuser. + +```{code} bash +poetry run python manage.py createsuperuser +``` + +That's it! You can log in as this user when you finish setting up Funkwhale. + +## Collect static files + +Funkwhale uses several static assets to serve its frontend. Use `manage.py` to collect these files so that the webserver can serve them. + +```{code} bash +poetry run python manage.py collectstatic +``` diff --git a/docs/administrator_documentation/installation_docs/debian/index.md b/docs/administrator_documentation/installation_docs/debian/index.md new file mode 100644 index 000000000..5a4a05920 --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/index.md @@ -0,0 +1,21 @@ +# Install Funkwhale on Debian + +We recommend using [Debian](https://debian.org) or a Debian-based Linux distribution to run Funkwhale. Follow the guides in this section to set up Funkwhale on a Debian server. + +```{toctree} +--- +caption: Installation steps +maxdepth: 1 +--- + +funkwhale_dependencies +create_user +download_funkwhale +python_dependencies +env_file +database +funkwhale_setup +systemd +reverse_proxy + +``` diff --git a/docs/administrator_documentation/installation_docs/debian/python_dependencies.md b/docs/administrator_documentation/installation_docs/debian/python_dependencies.md new file mode 100644 index 000000000..e0e4cfc86 --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/python_dependencies.md @@ -0,0 +1,24 @@ +# 4. Install Python dependencies + +The Funkwhale API is written in Python. You need to install the API's dependencies to run the software. We use [Poetry](https://python-poetry.org) to handle Python dependencies. + +1. Install Poetry. Follow the steps in this wizard to set it up. + + ```{code} bash + curl -sSL https://install.python-poetry.org | python3 - + ``` + +2. Add Poetry to your `$PATH`. This allows you to use `poetry` commands. + + ```{code} bash + export "$PATH=$HOME/.local/bin:$PATH" >> ~/.bashrc + ``` + +3. Set up poetry in your `/srv/funkwhale/api` directory. + + ```{code} bash + cd /srv/funkwhale/api + poetry install + ``` + +You're done! Poetry installs all Python dependencies. diff --git a/docs/administrator_documentation/installation_docs/debian/reverse_proxy.md b/docs/administrator_documentation/installation_docs/debian/reverse_proxy.md new file mode 100644 index 000000000..77cff933d --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/reverse_proxy.md @@ -0,0 +1,47 @@ +# 9. Set up a reverse proxy + +Funkwhale uses a reverse proxy to serve content to users. We use [Nginx](https://nginx.com) to serve this proxy. Follow this guide to install an Nginx configuration using details from your `.env` file. + +1. Install Nginx. + + ```{code} bash + sudo apt-get update + sudo apt-get install nginx + ``` + +2. Download the Nginx templates from Funkwhale. + + ```{code} bash + export FUNKWHALE_VERSION="1.2.1" + sudo curl -L -o /etc/nginx/funkwhale_proxy.conf "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/funkwhale_proxy.conf" + sudo curl -L -o /etc/nginx/sites-available/funkwhale.template "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/nginx.template" + ``` + +3. Create an Nginx template with details from your `.env` file. + + ```{code} bash + # Log in to a root shell. + + sudo su + + # Create an Nginx configuration using the Funkwhale template with details from your `.env` file. + + set -a && source /srv/funkwhale/config/.env && set +a + envsubst "`env | awk -F = '{printf \" $%s\", $$1}'`" \ + < /etc/nginx/sites-available/funkwhale.template \ + > /etc/nginx/sites-available/funkwhale.conf + + # Enable the configuration so that Nginx serves it. + + ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/ + + # Exit the root shell. + + exit + ``` + +That's it! You've created your Nginx file. Run the following command to check the `.env` details populated correctly. + +```{code} bash +grep '${' /etc/nginx/sites-enabled/funkwhale.conf +``` diff --git a/docs/administrator_documentation/installation_docs/debian/systemd.md b/docs/administrator_documentation/installation_docs/debian/systemd.md new file mode 100644 index 000000000..23fdf0e87 --- /dev/null +++ b/docs/administrator_documentation/installation_docs/debian/systemd.md @@ -0,0 +1,34 @@ +# 8. Set up systemd unit files + +Funkwhale uses [systemd](https://www.freedesktop.org/wiki/Software/systemd/) to manage its services. systemd helps prevent downtime by bringing services back up if they fail. It also starts your Funkwhale services after a reboot. Follow these steps to set up Funkwhale services with systemd. + +1. Download the sample unit files from Funkwhale. + + ```{code} bash + sudo curl -L -o "/etc/systemd/system/funkwhale.target" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/funkwhale.target" + sudo curl -L -o "/etc/systemd/system/funkwhale-server.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/funkwhale-server.service" + sudo curl -L -o "/etc/systemd/system/funkwhale-worker.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/funkwhale-worker.service" + sudo curl -L -o "/etc/systemd/system/funkwhale-beat.service" "https://dev.funkwhale.audio/funkwhale/funkwhale/raw/$FUNKWHALE_VERSION/deploy/funkwhale-beat.service" + ``` + +2. Reload systemd to register the new services. + + ```{code} bash + sudo systemctl daemon-reload + ``` + +3. Start all Funkwhale services. + + ```{code} bash + sudo systemctl start funkwhale.target + ``` + +4. Enable the services. Systemd can then start the services after a reboot. + + ```{code} bash + sudo systemctl enable funkwhale-server + sudo systemctl enable funkwhale-worker + sudo systemctl enable funkwhale-beat + ``` + +That's it! systemd keeps these services running and starts them up in the correct order after a reboot. diff --git a/docs/administrator_documentation/installation_docs/index.md b/docs/administrator_documentation/installation_docs/index.md new file mode 100644 index 000000000..7e8bbed6c --- /dev/null +++ b/docs/administrator_documentation/installation_docs/index.md @@ -0,0 +1,11 @@ +# Install Funkwhale on your server + +```{toctree} +--- +caption: Choose your installation method +maxdepth: 1 +--- + +debian/index + +``` diff --git a/docs/index.md b/docs/index.md index 1b23205bc..c1d847ebf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,7 +33,8 @@ caption: Admin documentation hidden: true --- -admin/index +administrator_documentation/index +administrator_documentation/installation_docs/index ``` @@ -126,7 +127,7 @@ Want to host your own Funkwhale pod? Our admin documentation guides you through +++ -```{link-button} admin/index +```{link-button} administrator_documentation/index :type: ref :text: Get started :classes: btn-outline-primary btn-block stretched-link