From 4f4c94cbbf4db751eddff132ad6ee1b7b2f5466d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Thu, 2 May 2024 16:35:25 +0200
Subject: [PATCH 01/13] Add docker documentation

---
 content/en/admin/docker.md | 123 +++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 content/en/admin/docker.md

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
new file mode 100644
index 0000000000..0d694c0081
--- /dev/null
+++ b/content/en/admin/docker.md
@@ -0,0 +1,123 @@
+---
+title: Run Mastodon inside Docker
+description: Setting Mastodon environnement using docker compose.
+menu:
+  docs:
+    weight: 30
+    parent: admin
+---
+
+# Mastodon configuration and environment variable generation {#Config and env variable generation}
+
+```sh
+# Clone Mastodon git repo
+git clone https://github.com/tootsuite/mastodon.git
+# Change directory to Mastodon
+cd mastodon
+# Checkout to the latest stable branch
+git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
+```
+
+In `docker-compose.yml` comment out the lines with `build: . ` for all images (web, streaming, sidekiq).  
+Then start the **postgres** db and the **redis**.
+
+```sh
+docker compose run db redis
+```
+
+By default the db is configured without a password via the parameter `POSTGRES_HOST_AUTH_METHOD=trust` and with the other parameters by default. It is strongly recommended to add a password to the db and to use another user, a database other than the default one etc... it is necessary to modify the `docker-compose.yml` to add the right variables for the **Postgres** container of the db service. You can refere to [the official documentation](https://hub.docker.com/_/postgres)
+
+Then get the ids of the 2 networks that will be created (`external_network` and `internal_network`). ( `docker network ls` ).  
+Then run the configuration script that will create the `.env.production`.
+
+```sh
+docker-compose run -it --rm --network <id-net-internal> --network <id-net-external> web bundle exec rake mastodon:setup
+```
+
+Fill in the required fields.  
+Finally, copy the contents of the generated `.env` and paste it into the `.env.production` on your machine.  
+Confirm the initial db setup when ask for.
+
+_If you don't want to configure the db now, you can run the following command later **Please note** this command requires the presence of the `.env.production` with the parameters to connect to the db:_.
+
+```sh
+docker-compose run --rm web bundle exec rails db:setup
+```
+
+If you have chosen to configure the db with the `mastodon:setup` script, validate the creation of the admin account when requested and copy the generated password.
+
+If the `mastodon:setup` script fails to initialize the db, it is necessary to add the `DISABLE_DATABASE_ENVIRONMENT_CHECK=1` variable to the container shell before restarting the command and validating the destruction of the database. Or you can remove the Postgres docker container and delete the volumes, and start again the db service with a fresh container.
+
+You can now start the Mastodon instance.
+
+```sh
+docker compose up -d
+```
+
+You can't access the Mastodon intance without configuring a reverse proxy like NGINX.
+
+# Reverse-proxy configuration {#Reverse-proxy configuration}
+
+## Creating a self-signed certificate {#Creating a self-signed certificate}
+
+Create a self-signed certificate for your Mastodon instance, if you want you can also use `certbot` to generate a certificate if you have your own public domaine.
+
+```sh
+sudo mkdir -p /etc/letsencrypt/live/<DNS-NAIME>/
+openssl req --nodes -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -sha256 -days 365
+sudo chmod root:root privkey.pem
+sudo chmod root:root fullchain.pem
+sudo mv privkey.pem /etc/letsencrypt/live/<DNS-NAIME>/
+sudo mv fullchain.pem /etc/letsencrypt/live/<DNS-NAIME>/
+```
+
+Fill in the requested fields, the `Common Name` field must be equal to the value of `LOCAL_DOMAIN` in the `.env.production`.
+
+## Nginx config {#Nginx config}
+
+Based on the [official configuration](https://github.com/mastodon/mastodon/blob/main/dist/nginx.conf), we modify a few elements to make the config work with docker.
+
+- `sed -i "s/try_files \$uri =404;/try_files \$uri @proxy;/" ~/nginx/conf/mastodon.conf`
+- `sed -i "s/server_name example.com;/\server_name <%WEB_DOMAIN%>;/" ~/nginx/conf/mastodon.con`
+- `sed -i 's/server 127.0.0.1:3000/server web:3000/' ~/nginx/conf/mastodon.conf`
+- `sed -i 's/server 127.0.0.1:4000/server streaming:4000/' ~/nginx/conf/mastodon.conf`
+- `sed -i 's/# ssl_certificate\s*\/etc\/letsencrypt\/live\/example.com\/fullchain.pem;/ssl_certificate\t\/etc\/letsencrypt\/live\/<%DNS NAME%>\/fullchain.pem;/' ~/conf/mastodon.conf`
+- `sed -i 's/# ssl_certificate_key\s*\/etc\/letsencrypt\/live\/example.com\/privkey.pem;/ssl_certificate_key\t\/etc\/letsencrypt\/live\/<%DNS NAME%>\/privkey.pem;/' ~/nginx/conf/mastodon.conf`
+
+Then start up the nginx container.
+
+```sh
+docker run --name nginx -p 80:80 -p 443:443 --network <id-net-internal> --network <id-net-external> -v ~/nginx/conf:/etc/nginx/conf.d:ro -v /etc/letsencrypt:/etc/letsencrypt:ro -d nginx
+```
+
+Test the instance with a browser. https://<dns-name>`
+
+# Finalization {#Finalization}
+
+## 1st Connection with admin account {#1st Connection with admin account}
+
+If you created the admin account with `mastodon:setup`, log in with the admin account email address and password. Change the default password. All that's left is to approve the admin account.  
+If not, connect to the container, create the admin account and approve it.
+
+```sh
+docker exec -it <id-web-container> bash
+
+RAILS_ENV=production
+
+tootctl accounts create \
+  alice \
+  --email alice@example.com \
+  --confirmed \
+  --role Owner
+
+tootctl accounts approve admin # pseudo du compte admin
+```
+
+## Admin account approval {#Admin account approval}
+
+Login to the container to validate the admin account:
+
+```sh
+docker exec -it <id-web-container> bash
+tootctl accounts approve admin # pseudo du compte admin
+```

From 54e0fa6e24dba5841a8a7569882b5a6a2ad1cd9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Sat, 6 Jul 2024 11:13:47 +0200
Subject: [PATCH 02/13] Improved documentation and harmonized commands.

---
 content/en/admin/docker.md | 69 ++++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 32 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 0d694c0081..5679a42204 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -22,31 +22,31 @@ In `docker-compose.yml` comment out the lines with `build: . ` for all images (w
 Then start the **postgres** db and the **redis**.
 
 ```sh
-docker compose run db redis
+docker compose pull
+docker compose up db redis
 ```
 
-By default the db is configured without a password via the parameter `POSTGRES_HOST_AUTH_METHOD=trust` and with the other parameters by default. It is strongly recommended to add a password to the db and to use another user, a database other than the default one etc... it is necessary to modify the `docker-compose.yml` to add the right variables for the **Postgres** container of the db service. You can refere to [the official documentation](https://hub.docker.com/_/postgres)
+By default, the db is configured without a password and with the other default parameters. If you wish to add a password to the db, or use a different user, table etc., you need to modify the `docker-compose.yml` to add the correct variables for the **Postgres** container of the db service.
 
-Then get the ids of the 2 networks that will be created (`external_network` and `internal_network`). ( `docker network ls` ).  
 Then run the configuration script that will create the `.env.production`.
 
 ```sh
-docker-compose run -it --rm --network <id-net-internal> --network <id-net-external> web bundle exec rake mastodon:setup
+docker compose run web bundle exec rake mastodon:setup
 ```
 
 Fill in the required fields.  
 Finally, copy the contents of the generated `.env` and paste it into the `.env.production` on your machine.  
-Confirm the initial db setup when ask for.
+Confirm the db setup.
 
-_If you don't want to configure the db now, you can run the following command later **Please note** this command requires the presence of the `.env.production` with the parameters to connect to the db:_.
+_If you don't want to configure the db now, you can run the following command later **Please note** this command requires the presence of the `.env.production` with the parameters to connect to the db:_
 
 ```sh
-docker-compose run --rm web bundle exec rails db:setup
+docker compose run web bundle exec rails db:setup
 ```
 
 If you have chosen to configure the db with the `mastodon:setup` script, validate the creation of the admin account when requested and copy the generated password.
 
-If the `mastodon:setup` script fails to initialize the db, it is necessary to add the `DISABLE_DATABASE_ENVIRONMENT_CHECK=1` variable to the container shell before restarting the command and validating the destruction of the database. Or you can remove the Postgres docker container and delete the volumes, and start again the db service with a fresh container.
+If the `mastodon:setup` script fails to initialize the db, add the variable `DISABLE_DATABASE_ENVIRONMENT_CHECK=1` in the container shell before re-running the command and validating the destruction of the database.
 
 You can now start the Mastodon instance.
 
@@ -56,51 +56,56 @@ docker compose up -d
 
 You can't access the Mastodon intance without configuring a reverse proxy like NGINX.
 
-# Reverse-proxy configuration {#Reverse-proxy configuration}
+## Reverse-proxy configuration {#Proxy configuration}
 
-## Creating a self-signed certificate {#Creating a self-signed certificate}
+### Creating a self-signed certificate
 
-Create a self-signed certificate for your Mastodon instance, if you want you can also use `certbot` to generate a certificate if you have your own public domaine.
+Create a self-signed certificate for your Mastodon instance.
 
 ```sh
-sudo mkdir -p /etc/letsencrypt/live/<DNS-NAIME>/
+DOMAIN_DNS='localhost'
 openssl req --nodes -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -sha256 -days 365
-sudo chmod root:root privkey.pem
-sudo chmod root:root fullchain.pem
-sudo mv privkey.pem /etc/letsencrypt/live/<DNS-NAIME>/
-sudo mv fullchain.pem /etc/letsencrypt/live/<DNS-NAIME>/
+mkdir -p "certs/live/$DOMAIN_DNS/"
+mv fullchain.pem privkey.pem certs/live/$DOMAIN_DNS/
 ```
 
-Fill in the requested fields, the `Common Name` field must be equal to the value of `LOCAL_DOMAIN` in the `.env.production`.
+Fill in the requested fields, the Common Name field must be equal to the value of `LOCAL_DOMAIN` in the `.env.production`.
 
-## Nginx config {#Nginx config}
+### Nginx config
 
 Based on the [official configuration](https://github.com/mastodon/mastodon/blob/main/dist/nginx.conf), we modify a few elements to make the config work with docker.
 
-- `sed -i "s/try_files \$uri =404;/try_files \$uri @proxy;/" ~/nginx/conf/mastodon.conf`
-- `sed -i "s/server_name example.com;/\server_name <%WEB_DOMAIN%>;/" ~/nginx/conf/mastodon.con`
-- `sed -i 's/server 127.0.0.1:3000/server web:3000/' ~/nginx/conf/mastodon.conf`
-- `sed -i 's/server 127.0.0.1:4000/server streaming:4000/' ~/nginx/conf/mastodon.conf`
-- `sed -i 's/# ssl_certificate\s*\/etc\/letsencrypt\/live\/example.com\/fullchain.pem;/ssl_certificate\t\/etc\/letsencrypt\/live\/<%DNS NAME%>\/fullchain.pem;/' ~/conf/mastodon.conf`
-- `sed -i 's/# ssl_certificate_key\s*\/etc\/letsencrypt\/live\/example.com\/privkey.pem;/ssl_certificate_key\t\/etc\/letsencrypt\/live\/<%DNS NAME%>\/privkey.pem;/' ~/nginx/conf/mastodon.conf`
+```sh
+DOMAIN_DNS='localhost'
+cp dist/nginx.conf dist/nginx_dockerized.conf
+sed -i "s/try_files \$uri =404;/try_files \$uri @proxy;/" dist/nginx_dockerized.conf
+sed -i "s/server_name example.com;/\server_name $DOMAIN_DNS;/" dist/nginx_dockerized.conf
+sed -i 's/server 127.0.0.1:3000/server web:3000/' dist/nginx_dockerized.conf
+sed -i 's/server 127.0.0.1:4000/server streaming:4000/' dist/nginx_dockerized.conf
+sed -i "s/# ssl_certificate\s*\/etc\/letsencrypt\/live\/example.com\/fullchain.pem;/ssl_certificate\t\/etc\/letsencrypt\/live\/$DOMAIN_DNS\/fullchain.pem;/" dist/nginx_dockerized.conf
+sed -i "s/# ssl_certificate_key\s*\/etc\/letsencrypt\/live\/example.com\/privkey.pem;/ssl_certificate_key\t\/etc\/letsencrypt\/live\/$DOMAIN_DNS\/privkey.pem;/" dist/nginx_dockerized.conf
+
+# Patch internal Host header forwarding
+sed -i "s/Host \$host/Host $DOMAIN_DNS/" dist/nginx_dockerized.conf
+```
 
 Then start up the nginx container.
 
 ```sh
-docker run --name nginx -p 80:80 -p 443:443 --network <id-net-internal> --network <id-net-external> -v ~/nginx/conf:/etc/nginx/conf.d:ro -v /etc/letsencrypt:/etc/letsencrypt:ro -d nginx
+docker compose up nginx -d
 ```
 
 Test the instance with a browser. https://<dns-name>`
 
-# Finalization {#Finalization}
+## Finalization {#Finalization}
 
-## 1st Connection with admin account {#1st Connection with admin account}
+### 1st Connection with admin account
 
 If you created the admin account with `mastodon:setup`, log in with the admin account email address and password. Change the default password. All that's left is to approve the admin account.  
 If not, connect to the container, create the admin account and approve it.
 
 ```sh
-docker exec -it <id-web-container> bash
+docker exec -it <id-conteneur-web> bash
 
 RAILS_ENV=production
 
@@ -110,14 +115,14 @@ tootctl accounts create \
   --confirmed \
   --role Owner
 
-tootctl accounts approve admin # pseudo du compte admin
+tootctl accounts approve admin # admin account username
 ```
 
-## Admin account approval {#Admin account approval}
+### Admin account approval
 
 Login to the container to validate the admin account:
 
 ```sh
-docker exec -it <id-web-container> bash
-tootctl accounts approve admin # pseudo du compte admin
+docker exec -it <id-conteneur-web> bash
+tootctl accounts approve admin # admin account username
 ```

From 884dd30c9f901a64041ee11ea95fd7316a3aa152 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Thu, 25 Dec 2025 01:47:37 +0100
Subject: [PATCH 03/13] Add Pre-requisites

---
 content/en/admin/docker.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 5679a42204..63680a52a7 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -7,7 +7,21 @@ menu:
     parent: admin
 ---
 
-# Mastodon configuration and environment variable generation {#Config and env variable generation}
+## Pre-requisites {#pre-requisites}
+
+* A machine running **Ubuntu 24.04** or **Debian 13** that you have root access to
+* A **domain name** (or a subdomain) for the Mastodon server, e.g. `example.com`
+* An email delivery service or other **SMTP server**
+* Latest Docker version installed with compose plugin 
+You will be running the commands as root. If you aren’t already root, switch to root: `sudo -i`
+
+{{< hint style="info" >}}
+It's advised to reed the [security section](https://docs.docker.com/engine/security/) of the docker documentation.
+{{< /hint >}}
+
+## Setup {#setup}
+
+### Retrieve the last mastodon release {#retrieve-the-last mastodon-release}
 
 ```sh
 # Clone Mastodon git repo

From 7d9bf1e5a2b85f663cc647eb8ce91bcc3f224345 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Thu, 25 Dec 2025 01:48:10 +0100
Subject: [PATCH 04/13] Update git instructions

---
 content/en/admin/docker.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 63680a52a7..f834bb25c2 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -25,11 +25,11 @@ It's advised to reed the [security section](https://docs.docker.com/engine/secur
 
 ```sh
 # Clone Mastodon git repo
-git clone https://github.com/tootsuite/mastodon.git
+git clone https://github.com/mastodon/mastodon.git
 # Change directory to Mastodon
 cd mastodon
 # Checkout to the latest stable branch
-git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
+git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
 ```
 
 In `docker-compose.yml` comment out the lines with `build: . ` for all images (web, streaming, sidekiq).  

From 6280b48f43a9663f63ab892e6b495f769d7bb99a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Thu, 25 Dec 2025 01:49:43 +0100
Subject: [PATCH 05/13] Update the bigging of the compose section

---
 content/en/admin/docker.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index f834bb25c2..8096b59d34 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -32,12 +32,33 @@ cd mastodon
 git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
 ```
 
-In `docker-compose.yml` comment out the lines with `build: . ` for all images (web, streaming, sidekiq).  
-Then start the **postgres** db and the **redis**.
+{{< hint style="info" >}}
+If you want to enable ElasticSearch uncomment the `es` service in the `docker-compose.yml`.
+
+If you want to enable federation with Tor instances uncomment the `tor` and the `privoxy` service in `docker-compose.yml`.
+And and the following environment variable to the `.env.production`:
+
+```sh
+http_hidden_proxy=http://privoxy:8118
+ALLOW_ACCESS_TO_HIDDEN_SERVICE=true
+```
+{{< /hint >}}
+
+### Generation of the `.env.production` file {#generation-of-the-`.env.production`-file}
+
+To generate your `.env.production` file you have several options :
+- Use the interactive setup wizard (recommended)
+- Use the .env.production.sample
+- Consult the [full config option list](https://docs.joinmastodon.org/admin/config/) and add the ones you need.
+
+
+First start the **postgres** db and the **redis**.
 
 ```sh
+# Pull all the images so you can work quickly later in the documentation
 docker compose pull
-docker compose up db redis
+# Start the Postgresql and the Redis database in detached mod
+docker compose up db redis -d
 ```
 
 By default, the db is configured without a password and with the other default parameters. If you wish to add a password to the db, or use a different user, table etc., you need to modify the `docker-compose.yml` to add the correct variables for the **Postgres** container of the db service.

From 998403d478ddfa0bcdc376aa74f4af82a8951106 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Thu, 25 Dec 2025 01:50:15 +0100
Subject: [PATCH 06/13] Update the Setup section

---
 content/en/admin/docker.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 8096b59d34..35c06df4e9 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -63,27 +63,34 @@ docker compose up db redis -d
 
 By default, the db is configured without a password and with the other default parameters. If you wish to add a password to the db, or use a different user, table etc., you need to modify the `docker-compose.yml` to add the correct variables for the **Postgres** container of the db service.
 
-Then run the configuration script that will create the `.env.production`.
+Then launch the configuration wizard, which will display the `.env.production`.
 
 ```sh
-docker compose run web bundle exec rake mastodon:setup
+docker compose run --rm web bundle exec rake mastodon:setup
 ```
 
 Fill in the required fields.  
 Finally, copy the contents of the generated `.env` and paste it into the `.env.production` on your machine.  
-Confirm the db setup.
+Confirm the PostgreSQL setup.
 
-_If you don't want to configure the db now, you can run the following command later **Please note** this command requires the presence of the `.env.production` with the parameters to connect to the db:_
+{{< hint style="info" >}}
+If for some reason you don't want to configure PostgreSQL now, you can run the following command later.
+**Please note** this command requires the presence of the `.env.production` with the parameters to connect to the db:
 
 ```sh
-docker compose run web bundle exec rails db:setup
+docker compose run --rm web bundle exec rails db:setup
 ```
+{{< /hint >}}
 
 If you have chosen to configure the db with the `mastodon:setup` script, validate the creation of the admin account when requested and copy the generated password.
 
 If the `mastodon:setup` script fails to initialize the db, add the variable `DISABLE_DATABASE_ENVIRONMENT_CHECK=1` in the container shell before re-running the command and validating the destruction of the database.
 
-You can now start the Mastodon instance.
+```sh
+docker compose run -e "DISABLE_DATABASE_ENVIRONMENT_CHECK=1" --rm web bundle exec rake mastodon:setup
+```
+
+You can now start all the Mastodon instance components.
 
 ```sh
 docker compose up -d

From c7697eefbbee6731ef3365b258d4ec308497510c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Thu, 25 Dec 2025 01:54:25 +0100
Subject: [PATCH 07/13] homogenization of the docker commands

---
 content/en/admin/docker.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 35c06df4e9..49f4e59ec0 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -147,7 +147,7 @@ If you created the admin account with `mastodon:setup`, log in with the admin ac
 If not, connect to the container, create the admin account and approve it.
 
 ```sh
-docker exec -it <id-conteneur-web> bash
+docker compose exec -it web bash
 
 RAILS_ENV=production
 
@@ -165,6 +165,6 @@ tootctl accounts approve admin # admin account username
 Login to the container to validate the admin account:
 
 ```sh
-docker exec -it <id-conteneur-web> bash
+docker compose exec -it web bash
 tootctl accounts approve admin # admin account username
 ```

From 4289aebeaeb8b4b1ba442c77110bb64ff4dd38f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Fri, 26 Dec 2025 19:43:10 +0100
Subject: [PATCH 08/13] Update pre-required to align with the official install
 method nginx via systemd not via docker

---
 content/en/admin/docker.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 49f4e59ec0..f2cd5952ba 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -13,12 +13,28 @@ menu:
 * A **domain name** (or a subdomain) for the Mastodon server, e.g. `example.com`
 * An email delivery service or other **SMTP server**
 * Latest Docker version installed with compose plugin 
-You will be running the commands as root. If you aren’t already root, switch to root: `sudo -i`
 
 {{< hint style="info" >}}
 It's advised to reed the [security section](https://docs.docker.com/engine/security/) of the docker documentation.
 {{< /hint >}}
 
+You will be running the commands as root. If you aren’t already root, switch to root: `sudo -i`
+
+### Creating the `mastodon` user {#creating-the-mastodon-user}
+
+This is the user account under which Mastodon will live:
+
+```bash
+adduser --disabled-password mastodon
+```
+
+### System packages {#system-packages}
+
+```bash
+apt update
+apt install -y certbot nginx python3-certbot-nginx
+```
+
 ## Setup {#setup}
 
 ### Retrieve the last mastodon release {#retrieve-the-last mastodon-release}

From 340acead434ee5ff2bc762abe9094930a3f0792b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Fri, 26 Dec 2025 19:46:50 +0100
Subject: [PATCH 09/13] Updated the repository retrieval method to be
 compatible with the default nginx configuration file.

---
 content/en/admin/docker.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index f2cd5952ba..f417bfea72 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -39,22 +39,24 @@ apt install -y certbot nginx python3-certbot-nginx
 
 ### Retrieve the last mastodon release {#retrieve-the-last mastodon-release}
 
-```sh
+```bash
+su - mastodon
 # Clone Mastodon git repo
-git clone https://github.com/mastodon/mastodon.git
-# Change directory to Mastodon
-cd mastodon
+git clone https://github.com/mastodon/mastodon.git live
+# Change directory to Mastodon repo
+cd live
 # Checkout to the latest stable branch
-git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
+git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1) && exit
 ```
 
+### Review the `docker-compose.yml` {#review-the-compose-file}
 {{< hint style="info" >}}
 If you want to enable ElasticSearch uncomment the `es` service in the `docker-compose.yml`.
 
 If you want to enable federation with Tor instances uncomment the `tor` and the `privoxy` service in `docker-compose.yml`.
 And and the following environment variable to the `.env.production`:
 
-```sh
+```bash
 http_hidden_proxy=http://privoxy:8118
 ALLOW_ACCESS_TO_HIDDEN_SERVICE=true
 ```

From 27bd266ef25f6a4108b9d3e439539d95021a1902 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Fri, 26 Dec 2025 19:52:15 +0100
Subject: [PATCH 10/13] Improve the section on generating the .env file and
 walk through the wizard.

---
 content/en/admin/docker.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index f417bfea72..89bbb55610 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -62,7 +62,7 @@ ALLOW_ACCESS_TO_HIDDEN_SERVICE=true
 ```
 {{< /hint >}}
 
-### Generation of the `.env.production` file {#generation-of-the-`.env.production`-file}
+### Generation of the `.env.production` file {#generation-of-the-.env.production-file}
 
 To generate your `.env.production` file you have several options :
 - Use the interactive setup wizard (recommended)
@@ -72,7 +72,8 @@ To generate your `.env.production` file you have several options :
 
 First start the **postgres** db and the **redis**.
 
-```sh
+```bash
+# Be sure to be root and in the /home/mastodon/live/ directory
 # Pull all the images so you can work quickly later in the documentation
 docker compose pull
 # Start the Postgresql and the Redis database in detached mod
@@ -83,39 +84,38 @@ By default, the db is configured without a password and with the other default p
 
 Then launch the configuration wizard, which will display the `.env.production`.
 
-```sh
+```bash
 docker compose run --rm web bundle exec rake mastodon:setup
 ```
 
 Fill in the required fields.  
 Finally, copy the contents of the generated `.env` and paste it into the `.env.production` on your machine.  
+
 Confirm the PostgreSQL setup.
 
 {{< hint style="info" >}}
 If for some reason you don't want to configure PostgreSQL now, you can run the following command later.
 **Please note** this command requires the presence of the `.env.production` with the parameters to connect to the db:
 
-```sh
+```bash
 docker compose run --rm web bundle exec rails db:setup
 ```
 {{< /hint >}}
 
-If you have chosen to configure the db with the `mastodon:setup` script, validate the creation of the admin account when requested and copy the generated password.
+Validate the creation of the admin account when requested and copy the generated password.
 
 If the `mastodon:setup` script fails to initialize the db, add the variable `DISABLE_DATABASE_ENVIRONMENT_CHECK=1` in the container shell before re-running the command and validating the destruction of the database.
 
-```sh
+```bash
 docker compose run -e "DISABLE_DATABASE_ENVIRONMENT_CHECK=1" --rm web bundle exec rake mastodon:setup
 ```
 
 You can now start all the Mastodon instance components.
 
-```sh
+```bash
 docker compose up -d
 ```
 
-You can't access the Mastodon intance without configuring a reverse proxy like NGINX.
-
 ## Reverse-proxy configuration {#Proxy configuration}
 
 ### Creating a self-signed certificate

From 50689e3e17e50b1db84f18d02329899e6571547f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Fri, 26 Dec 2025 19:59:29 +0100
Subject: [PATCH 11/13] Update nginx setup instruction to align with official
 systemd setup and comply with mastodon/mastodon@1a31c41

---
 content/en/admin/docker.md | 71 ++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 33 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 89bbb55610..fa64fda81e 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -118,57 +118,62 @@ docker compose up -d
 
 ## Reverse-proxy configuration {#Proxy configuration}
 
-### Creating a self-signed certificate
+To access the Mastodon web instance you need to configure a proxy, like Nginx.
 
-Create a self-signed certificate for your Mastodon instance.
+The mastodon web and streaming service are listening on 127.0.0.1 so you need setup nginx to redirect the traffic from port 80 and 443 of you machine to the web and streaming container which are listening on 127.0.0.1.
 
-```sh
-DOMAIN_DNS='localhost'
-openssl req --nodes -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -sha256 -days 365
-mkdir -p "certs/live/$DOMAIN_DNS/"
-mv fullchain.pem privkey.pem certs/live/$DOMAIN_DNS/
+### Acquiring an SSL certificate {#acquiring-an-ssl-certificate}
+
+We’ll use Let’s Encrypt to get a free SSL certificate:
+
+```bash
+certbot certonly --nginx -d example.com
 ```
 
-Fill in the requested fields, the Common Name field must be equal to the value of `LOCAL_DOMAIN` in the `.env.production`.
+This will obtain the certificate, and save it in the directory `/etc/letsencrypt/live/example.com/`.
 
-### Nginx config
+### Setting up NGINX {#setting-up-nginx}
 
-Based on the [official configuration](https://github.com/mastodon/mastodon/blob/main/dist/nginx.conf), we modify a few elements to make the config work with docker.
+Copy the configuration template for nginx from the Mastodon directory:
 
-```sh
-DOMAIN_DNS='localhost'
-cp dist/nginx.conf dist/nginx_dockerized.conf
-sed -i "s/try_files \$uri =404;/try_files \$uri @proxy;/" dist/nginx_dockerized.conf
-sed -i "s/server_name example.com;/\server_name $DOMAIN_DNS;/" dist/nginx_dockerized.conf
-sed -i 's/server 127.0.0.1:3000/server web:3000/' dist/nginx_dockerized.conf
-sed -i 's/server 127.0.0.1:4000/server streaming:4000/' dist/nginx_dockerized.conf
-sed -i "s/# ssl_certificate\s*\/etc\/letsencrypt\/live\/example.com\/fullchain.pem;/ssl_certificate\t\/etc\/letsencrypt\/live\/$DOMAIN_DNS\/fullchain.pem;/" dist/nginx_dockerized.conf
-sed -i "s/# ssl_certificate_key\s*\/etc\/letsencrypt\/live\/example.com\/privkey.pem;/ssl_certificate_key\t\/etc\/letsencrypt\/live\/$DOMAIN_DNS\/privkey.pem;/" dist/nginx_dockerized.conf
-
-# Patch internal Host header forwarding
-sed -i "s/Host \$host/Host $DOMAIN_DNS/" dist/nginx_dockerized.conf
+```bash
+cp /root/mastodon/dist/nginx.conf /etc/nginx/sites-available/mastodon
+ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
+rm /etc/nginx/sites-enabled/default
 ```
 
-Then start up the nginx container.
+Then edit `/etc/nginx/sites-available/mastodon` to 
 
-```sh
-docker compose up nginx -d
+1. Replace `example.com` with your own domain name
+2. Uncomment the `ssl_certificate` and `ssl_certificate_key` (ignore this step if you are bringing your own certificate):
+
+    ```nginx
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;;
+    ```
+
+3. Uncomment the `# try_files $uri @mastodon;` instruction in the `location ^~ /assets/`, `location ^~ /packs/` and `location ^~ /system/` scop.
+
+Allow other users to traverse the mastodon user's home directory, so that nginx's `www-data` user can access asset files:
+
+```bash
+chmod o+x /home/mastodon
 ```
 
-Test the instance with a browser. https://<dns-name>`
+Restart nginx for the changes to take effect:
 
-## Finalization {#Finalization}
+```bash
+systemctl restart nginx
+```
 
-### 1st Connection with admin account
+At this point, you should be able to visit your domain in the browser. If you didn't create the admin account with the wizard follow the additional step.
 
-If you created the admin account with `mastodon:setup`, log in with the admin account email address and password. Change the default password. All that's left is to approve the admin account.  
-If not, connect to the container, create the admin account and approve it.
+## Additional step {#Additional-step}
+Connect to the web container and create the admin account, don't forget to approve the account.
 
-```sh
+```bash
 docker compose exec -it web bash
 
-RAILS_ENV=production
-
 tootctl accounts create \
   alice \
   --email alice@example.com \

From 26468b87f9e53561c304e9c133150d4af52c0433 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Fri, 26 Dec 2025 20:01:43 +0100
Subject: [PATCH 12/13] Remove the admin account confirmation step since now
 the admin account is confirmed by the wizard.

---
 content/en/admin/docker.md | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index fa64fda81e..3ced5310cf 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -180,14 +180,7 @@ tootctl accounts create \
   --confirmed \
   --role Owner
 
-tootctl accounts approve admin # admin account username
-```
-
-### Admin account approval
+tootctl accounts approve alice
 
-Login to the container to validate the admin account:
-
-```sh
-docker compose exec -it web bash
-tootctl accounts approve admin # admin account username
+exit
 ```

From 55fff540e9220ec30becb0b16dfe9a9099256394 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arc=C3=A9lone?= <62914065+Arcelone@users.noreply.github.com>
Date: Sat, 31 Jan 2026 19:29:29 +0100
Subject: [PATCH 13/13] Correction of errors, adjustment of syntax and style to
 match the overall style of the documentation.

---
 content/en/admin/docker.md | 75 ++++++++++++++++++++++----------------
 1 file changed, 43 insertions(+), 32 deletions(-)

diff --git a/content/en/admin/docker.md b/content/en/admin/docker.md
index 3ced5310cf..964a721ab9 100644
--- a/content/en/admin/docker.md
+++ b/content/en/admin/docker.md
@@ -1,6 +1,6 @@
 ---
 title: Run Mastodon inside Docker
-description: Setting Mastodon environnement using docker compose.
+description: Setting up a Mastodon environment using Docker Compose.
 menu:
   docs:
     weight: 30
@@ -12,12 +12,14 @@ menu:
 * A machine running **Ubuntu 24.04** or **Debian 13** that you have root access to
 * A **domain name** (or a subdomain) for the Mastodon server, e.g. `example.com`
 * An email delivery service or other **SMTP server**
-* Latest Docker version installed with compose plugin 
+* The latest **Docker Engine** version with the **Docker Compose plugin** installed
 
 {{< hint style="info" >}}
-It's advised to reed the [security section](https://docs.docker.com/engine/security/) of the docker documentation.
+Before proceeding, it's advised to read the [security section](https://docs.docker.com/engine/security/) of the Docker documentation.
 {{< /hint >}}
 
+We will be using `example.com` as the domain in the following example. Please remember to replace it with your own domain before running any commands.
+
 You will be running the commands as root. If you aren’t already root, switch to root: `sudo -i`
 
 ### Creating the `mastodon` user {#creating-the-mastodon-user}
@@ -30,6 +32,8 @@ adduser --disabled-password mastodon
 
 ### System packages {#system-packages}
 
+Install the packages required for HTTPS certificates and reverse proxying:
+
 ```bash
 apt update
 apt install -y certbot nginx python3-certbot-nginx
@@ -37,7 +41,9 @@ apt install -y certbot nginx python3-certbot-nginx
 
 ## Setup {#setup}
 
-### Retrieve the last mastodon release {#retrieve-the-last mastodon-release}
+### Retrieving the latest Mastodon release {#retrieving-the-latest-mastodon-release}
+
+Switch to the `mastodon` user and use git to download the latest stable release of Mastodon:
 
 ```bash
 su - mastodon
@@ -45,51 +51,54 @@ su - mastodon
 git clone https://github.com/mastodon/mastodon.git live
 # Change directory to Mastodon repo
 cd live
-# Checkout to the latest stable branch
+# Check out the latest stable release
 git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1) && exit
 ```
 
-### Review the `docker-compose.yml` {#review-the-compose-file}
-{{< hint style="info" >}}
-If you want to enable ElasticSearch uncomment the `es` service in the `docker-compose.yml`.
+### Reviewing the `docker-compose.yml` file {#review-the-docker-compose-file}
+
+The file is functional, but you may want to enable optional services depending on your use case.
 
+**Elasticsearch**.  
+If you want to enable Elasticsearch uncomment the `es` service in the `docker-compose.yml`.
+
+**Federation with Tor instances**  
 If you want to enable federation with Tor instances uncomment the `tor` and the `privoxy` service in `docker-compose.yml`.
-And and the following environment variable to the `.env.production`:
+Add the following environment variable to the `.env.production`:
 
 ```bash
 http_hidden_proxy=http://privoxy:8118
 ALLOW_ACCESS_TO_HIDDEN_SERVICE=true
 ```
-{{< /hint >}}
-
-### Generation of the `.env.production` file {#generation-of-the-.env.production-file}
 
-To generate your `.env.production` file you have several options :
-- Use the interactive setup wizard (recommended)
-- Use the .env.production.sample
-- Consult the [full config option list](https://docs.joinmastodon.org/admin/config/) and add the ones you need.
+### Generating the `.env.production` file {#generation-of-the-.env.production-file}
 
+You can generate the `.env.production` file in several ways:
+- Using the interactive setup wizard (**recommended**)
+- Copying the .env.production.sample
+- Consulting the [full config option list](https://docs.joinmastodon.org/admin/config/) and add the ones you need.
 
 First start the **postgres** db and the **redis**.
+Make sure you are **root** and in `/home/mastodon/live`:
 
 ```bash
-# Be sure to be root and in the /home/mastodon/live/ directory
 # Pull all the images so you can work quickly later in the documentation
 docker compose pull
-# Start the Postgresql and the Redis database in detached mod
-docker compose up db redis -d
+# Start the Postgresql and the Redis database in detached mode
+docker compose up -d db redis
 ```
 
-By default, the db is configured without a password and with the other default parameters. If you wish to add a password to the db, or use a different user, table etc., you need to modify the `docker-compose.yml` to add the correct variables for the **Postgres** container of the db service.
+By default, PostgreSQL is configured without a password and uses the default user and database defined in `docker-compose.yml`.  
+If you wish to add a password to the database, or use a different user, table etc., you need to edit the `db` service in the `docker-compose.yml` to add the correct variables for the **Postgres** container.
 
-Then launch the configuration wizard, which will display the `.env.production`.
+You can now launch the configuration wizard. It will display the `.env.production` after a few questions.
 
 ```bash
 docker compose run --rm web bundle exec rake mastodon:setup
 ```
 
 Fill in the required fields.  
-Finally, copy the contents of the generated `.env` and paste it into the `.env.production` on your machine.  
+Finally, copy the contents of the generated `.env` and paste it into the `.env.production` on your host.  
 
 Confirm the PostgreSQL setup.
 
@@ -116,11 +125,11 @@ You can now start all the Mastodon instance components.
 docker compose up -d
 ```
 
-## Reverse-proxy configuration {#Proxy configuration}
+## Reverse proxy configuration {#reverse-proxy-configuration}
 
-To access the Mastodon web instance you need to configure a proxy, like Nginx.
+To access the Mastodon web instance you must configure a reverse proxy, such as `nginx`.
 
-The mastodon web and streaming service are listening on 127.0.0.1 so you need setup nginx to redirect the traffic from port 80 and 443 of you machine to the web and streaming container which are listening on 127.0.0.1.
+The Mastodon web and streaming services listen on `127.0.0.1`. nginx will forward incoming traffic from port **80** and **443** of your host to these containers, which are listening on 127.0.0.1.
 
 ### Acquiring an SSL certificate {#acquiring-an-ssl-certificate}
 
@@ -132,12 +141,12 @@ certbot certonly --nginx -d example.com
 
 This will obtain the certificate, and save it in the directory `/etc/letsencrypt/live/example.com/`.
 
-### Setting up NGINX {#setting-up-nginx}
+### Setting up nginx {#setting-up-nginx}
 
 Copy the configuration template for nginx from the Mastodon directory:
 
 ```bash
-cp /root/mastodon/dist/nginx.conf /etc/nginx/sites-available/mastodon
+cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
 ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
 rm /etc/nginx/sites-enabled/default
 ```
@@ -152,7 +161,7 @@ Then edit `/etc/nginx/sites-available/mastodon` to
     ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;;
     ```
 
-3. Uncomment the `# try_files $uri @mastodon;` instruction in the `location ^~ /assets/`, `location ^~ /packs/` and `location ^~ /system/` scop.
+3. Uncomment the `# try_files $uri @mastodon;` instruction in the `location ^~ /assets/`, `location ^~ /packs/` and `location ^~ /system/` scopes.
 
 Allow other users to traverse the mastodon user's home directory, so that nginx's `www-data` user can access asset files:
 
@@ -166,16 +175,18 @@ Restart nginx for the changes to take effect:
 systemctl restart nginx
 ```
 
-At this point, you should be able to visit your domain in the browser. If you didn't create the admin account with the wizard follow the additional step.
+You should now be able to access your Mastodon instance in a web browser.
+
+## Creating an administrator account manually {#creating-an-administrator-account-manually}
+
+If you did not create an administrator account during the setup wizard, you can create one manually.
 
-## Additional step {#Additional-step}
 Connect to the web container and create the admin account, don't forget to approve the account.
 
 ```bash
 docker compose exec -it web bash
 
-tootctl accounts create \
-  alice \
+tootctl accounts create alice \
   --email alice@example.com \
   --confirmed \
   --role Owner