Skip to content

Deployment Overview of Mastodon on Server

Prerequisites and Basic Requirements

To ensure a successful deployment, the following requirements must be met:

  • Operating System: Ubuntu (latest stable version recommended).

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

  • Domain: A valid FQDN configured to point to the server's IP address.

  • Ports: The following ports must be open on the host firewall:

  • 80/tcp (HTTP)

  • 443/tcp (HTTPS)

  • 3000/tcp (Web application internal access)

  • 4000/tcp (Streaming service internal access)

FQDN of the final panel on the hostkey.in domain

The application is accessible via a specific subdomain template based on your server ID:

Parameter Value
Prefix mastodon
Domain hostkey.in
Full template mastodon{Server_ID_from_Invapi}.hostkey.in

File and Directory Structure

The application uses a dedicated directory for all configuration files, environment variables, and persistent data:

  • Application Root: /opt/mastodon

  • Database Data: /opt/mastodon/data/postgres

  • Redis Data: /opt/mastodon/data/redis

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

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

Application installation process

The deployment follows a structured process to set up the environment and initialize the application:

  1. System Preparation: The system is updated, and Docker and the Docker Compose plugin are installed.

  2. User Creation: A dedicated service user named mastodon is created with its home directory set to /opt/mastodon.

  3. Directory Initialization: All necessary data directories for PostgreSQL, Redis, and public assets are created with appropriate ownership (mastodon:mastodon) and permissions (0755).

  4. Environment Configuration:

  5. A database environment file .env.db is generated to manage credentials.

  6. A production environment file .env.production is prepared, containing federation settings, Redis/PostgreSQL connection details, and security secrets.

  7. Secret Generation: The system automatically generates several critical security keys using the application's internal tools:

  8. SECRET_KEY_BASE

  9. OTP_SECRET

  10. VAPID Keys (for Web Push notifications)

  11. Database Encryption Keys and Salt (ACTIVE_RECORD_ENCRYPTION_...)

  12. Container Deployment: The application is launched using Docker Compose.

  13. Database Initialization:

  14. A database readiness check is performed to ensure PostgreSQL is active.

  15. Pre-deployment migrations are executed.

  16. Post-deployment migrations are run to finalize the schema.

  17. Data Seeding: An initial admin user and necessary seed data are created within the database.

Access Rights and Security

  • Service User: The application runs under the mastodon user to limit process privileges.

  • File Permissions: Sensitive environment files (.env.db, .env.production) are restricted with mode 0600.

  • Network Isolation: Docker containers communicate over a private internal network, isolating the database and Redis from external access.

  • SSL/TLS: Traffic is secured via Nginx using SSL certificates managed by Certbot.

Databases

The application utilizes two primary data stores:

Database Type Connection Method Storage Location
PostgreSQL Relational (SQL) Internal Docker Network ./postgres14
Redis In-memory Key-Value Internal Docker Network ./redis

Docker Containers and Their Deployment

The application is composed of several interconnected containers defined in docker-compose.yml:

  • nginx

  • Image: jonasal/nginx-certbot:latest

  • Ports: Host network mode (handles SSL termination)

  • Volumes:

  • nginx_secrets:/etc/letsencrypt

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

  • Restart Policy: unless-stopped

  • db

  • Image: postgres:14-alpine

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

  • Networks: internal_network

  • Restart Policy: always

  • redis

  • Image: redis:7-alpine

  • Volumes: ./redis:/data

  • Networks: internal_network

  • Restart Policy: always

  • web

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

  • Ports: 0.0.0.0:3000:3000

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

  • Networks: external_network, internal_network

  • Restart Policy: always

  • streaming

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

  • Ports: 0.0.0.0:4000:4000

  • Networks: external_network, internal_network

  • Restart Policy: always

  • sidekiq

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

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

  • Networks: external_network, internal_network

  • Restart Policy: always

Application Update Instructions

To update the Mastodon application, execute the following command within the /opt/mastodon directory:

docker compose pull && docker compose up -d

This will pull the latest images for the web and streaming services and restart the containers.

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×