Deployment Overview of Mastodon on Server¶

Prerequisites and Basic Requirements¶

To deploy Mastodon, the server must meet the following requirements:

• Operating System: Ubuntu.

• Privileges: Root or sudo access is required for package installation and system configuration.

• Domain: A valid FQDN within the hostkey.in zone is required for SSL and federation.

• Ports:

• 80/TCP: HTTP (for Certbot/Nginx redirection).

• 443/TCP: HTTPS (Main application access).

• 3000/TCP: Mastodon Web service.

• 4000/TCP: Mastodon Streaming service.

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a dynamically generated subdomain based on the server ID.

File and Directory Structure¶

The application uses a dedicated service user (mastodon) to manage files located in /opt/mastodon.

• Application Root: /opt/mastodon

• Database Data: /opt/mastodon/data/postgres (managed via Docker volume)

• Redis Data: /opt/mastodon/data/redis (managed via Docker volume)

• Public Assets: /opt/mastodon/data/public/system

• Nginx Configurations: /data/nginx/user_conf.d/

• SSL Certificates: Managed in /etc/letsencrypt via the nginx_secrets volume.

Application Installation Process¶

The installation process follows these steps:

1. System Preparation: Docker and Docker Compose are installed on the host system. A dedicated user named mastodon is created to run the services.

2. Environment Setup:

3. The directory structure for data persistence is initialized with appropriate ownership (mastodon:mastodon).

4. Environment files .env.db (for database credentials) and .env.production (for application settings) are generated.

5. Secret Generation: The system automatically generates several security keys using the Mastodon container to ensure high entropy:

6. SECRET_KEY_BASE

7. OTP_SECRET

8. VAPID Keys (VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY) for Web Push.

9. ActiveRecord Encryption keys and salt.

10. Service Deployment: The application is deployed using Docker Compose.

11. Database Initialization:

12. PostgreSQL service is verified for readiness.

13. Database migrations are executed in two stages: pre-deployment (to prepare schema) and post-deployment (to finalize changes).

14. Data Seeding: An initial admin user and essential data are created via the db:seed command.

Access Rights and Security¶

• User Isolation: All application processes run under the mastodon service user.

• File Permissions: Configuration files containing secrets (like .env.production) are restricted with mode 0600.

• Network Isolation: Docker containers communicate over an internal network (internal_network), while only necessary ports are exposed to the host or external networks.

Databases¶

The application utilizes two primary database engines:

Docker Containers and Their Deployment¶

The deployment consists of several containers managed via docker-compose.yml.

Nginx Proxy Container¶

• Image: jonasal/nginx-certbot:latest

• Ports: Host network mode (listens on 80 and 443).

• Volumes:

• nginx_secrets:/etc/letsencrypt

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d

• Purpose: Handles SSL termination via Certbot and proxies traffic to the application containers.

Database Container¶

• Image: postgres:14-alpine

• Volumes: ./postgres14:/var/lib/postgresql/data

• Environment Variables: POSTGRES_HOST_AUTH_METHOD=trust

• Restart Policy: always

Redis Container¶

• Image: redis:7-alpine

• Volumes: ./redis:/data

• Restart Policy: always

Web Application Container¶

• Image: ghcr.io/mastodon/mastodon:v4.3.1

• Ports: 0.0.0.0:3000:3000

• Volumes: ./public/system:/mastodon/public/system

• Environment Variables: Loaded from .env.production

• Restart Policy: always

Streaming Container¶

• Image: ghcr.io/mastodon/mastodon-streaming:v4.3.1

• Ports: 0.0.0.0:4000:4000

• Environment Variables: Loaded from .env.production

• Restart Policy: always

Sidekiq Container (Background Jobs)¶

• Image: ghcr.io/mastodon/mastodon:v4.3.1

• Volumes: ./public/system:/mastodon/public/system

• Environment Variables: Loaded from .env.production

• Restart Policy: always

Application Update Instructions¶

To update the Mastodon application, perform the following steps in the /opt/mastodon directory:

1. Pull the latest images for the web and streaming services:

   docker compose pull
   

2. Apply changes by restarting the containers:

   docker compose up -d
   

Location of Configuration Files and Data¶

Available Ports for Connection¶

• HTTPS (Web Interface): 443

• Streaming API: 4000