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:
-
System Preparation: The system is updated, and Docker and the Docker Compose plugin are installed.
-
User Creation: A dedicated service user named
mastodonis created with its home directory set to/opt/mastodon. -
Directory Initialization: All necessary data directories for PostgreSQL, Redis, and public assets are created with appropriate ownership (
mastodon:mastodon) and permissions (0755). -
Environment Configuration:
-
A database environment file
.env.dbis generated to manage credentials. -
A production environment file
.env.productionis prepared, containing federation settings, Redis/PostgreSQL connection details, and security secrets. -
Secret Generation: The system automatically generates several critical security keys using the application's internal tools:
-
SECRET_KEY_BASE -
OTP_SECRET -
VAPID Keys (for Web Push notifications)
-
Database Encryption Keys and Salt (
ACTIVE_RECORD_ENCRYPTION_...) -
Container Deployment: The application is launched using Docker Compose.
-
Database Initialization:
-
A database readiness check is performed to ensure PostgreSQL is active.
-
Pre-deployment migrations are executed.
-
Post-deployment migrations are run to finalize the schema.
-
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
mastodonuser to limit process privileges. -
File Permissions: Sensitive environment files (
.env.db,.env.production) are restricted with mode0600. -
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:
This will pull the latest images for the web and streaming services and restart the containers.