Recently I’ve setup an invite-only mastodon instance as a private space for
friends and family. While I am still evaluating whether mastodon is the right tool for such a private space, I’d like to share a number of issues I encountered during setup.
Careful with non-official guides
The mastodon documentation focuses on hosting mastodon on a dedicated machine. It is thorough and I would recommend reading through it, even if you do not want to dedicate a separate machine to hosting mastodon. Mastodon also maintains a
docker-compose config file, unfortunately the documentation on setting it up appears lackluster. The best guides I’ve found details are a alibaba cloud guide and a howtoforge guide. Note these guides aren’t perfect: the official docs recommend running the latest tagged releases whereas both guides run from the master branch, generating the necessary secrets is done differently than in the official documentation and I also don’t like how they automate certificate renewal.
Issues related to the db service
After initial tweaking of the
.env.production file I encountered two issues related to the db service. Fortunately I stumbled upon this stackoverflow answer. I recap my findings belows.
rails aborted! PG::ConnectionBad: could not connect to server: No such file or directory
This is caused by the web service being unable to connect to the database. In my case this was due to an invalid value for
mastodon_db_1 solved this issue for me. The resulting postgres section looks as follows:
# PostgreSQL # ---------- DB_HOST=mastodon_db_1 DB_USER=mastodon DB_NAME=mastodon_production DB_PASS=xyz DB_PORT=5432
In the same vain you’ll want to change
Error: Database is uninitialized and superuser password is not specified. You must specify POSTGRES_PASSWORD to a non-empty value for the superuser
This is caused by the
pg_isready healthcheck failing and can be fixed by setting the necessary env variables in
docker-compose.yml. The resulting
db compose service looks as follows:
db: restart: always image: postgres:9.6-alpine shm_size: 256mb networks: - internal_network healthcheck: test: ["CMD", "pg_isready", "-U", "mastodon", "-d", "mastodon_production"] volumes: - ./postgres:/var/lib/postgresql/data environment: POSTGRES_PASSWORD: xyz POSTGRES_DB: mastodon_production POSTGRES_USER: mastodon
Optional features enabled by default
s3 object storage
This is enabled by default in the sample environment file. If you don’t configure it correctly (or forget to turn it off), you’ll notice that media uploads are failing. The failures are accompanied by the following log message:
method=POST path=/api/v2/media format=html controller=Api::V2::MediaController action=create status=500 error='Aws::Sigv4::Errors::MissingCredentialsError: missing credentials,provide credentials with one of the following options.
If you want to store media on local storage, just comment the lines under File Storage in the env file. Do check to ensure that
/opt/mastodon/public/system/ in the web container is persisted on the host system (this should be case via the volume defined in the
Elastic search is also enabled by default in the sample env file, while it is commented out in the
docker-compose.yml file. If you don’t have the
es containter running, you’ll notice a large number of sidekiq jobs starting to accumulate in the ‘Retry’ state with the following error message:
Faraday::ConnectionFailed: Failed to open TCP connection to localhost:9200 (Cannot assign requested address - connect(2) for "localhost" port 9200). Either enable the
es container or comment out
ES_ENABLED=true in the ENV file.
My entire ENV file
For completeness you can find my entire
.env.production file below, where sensitive entries have been redacted. Note I am currently using mailgun as an SMTP server, as I found sendgrid to be blocked by Spam filters.
# This is a sample configuration file. You can generate your configuration # with the `rake mastodon:setup` interactive setup wizard, but to customize # your setup even further, you'll need to edit it manually. This sample does # not demonstrate all available configuration options. Please look at # https://docs.joinmastodon.org/admin/config/ for the full documentation. # Federation # ---------- # This identifies your server and cannot be changed safely later # ---------- LOCAL_DOMAIN=social.vdna.be # Redis # ----- REDIS_HOST=mastodon_redis_1 REDIS_PORT=6379 # PostgreSQL # ---------- DB_HOST=mastodon_db_1 DB_USER=mastodon DB_NAME=mastodon_production DB_PASS=xyz DB_PORT=5432 # ElasticSearch (optional) # ------------------------ # ES_ENABLED=true # ES_HOST=localhost # ES_PORT=9200 # Secrets # ------- # Make sure to use `rake secret` to generate secrets # ------- SECRET_KEY_BASE=xyz OTP_SECRET=xyz # Web Push # -------- # Generate with `rake mastodon:webpush:generate_vapid_key` # -------- VAPID_PRIVATE_KEY=xyz VAPID_PUBLIC_KEY=xyz # Sending mail # ------------ SMTP_SERVER=smtp.eu.mailgun.org SMTP_PORT=587 SMTP_LOGINemail@example.com SMTP_PASSWORD=xyz SMTP_FROM_ADDRESSfirstname.lastname@example.org # File storage (optional) # ----------------------- #S3_ENABLED=true #S3_BUCKET=files.example.com #AWS_ACCESS_KEY_ID= #AWS_SECRET_ACCESS_KEY= #S3_ALIAS_HOST=files.example.com