[19.0][NEW-APP]MASTODON ~ \o/

[marcos-mendez]

New Appliance: Mastodon — Federated Social Network

TL;DR

We have a fully working TurnKey Mastodon appliance (v4.5.8) building cleanly on TKLDev 19.x-dev (Trixie). ISO tested, firstboot working, and the same stack is already running in production at [organica.social](https://organica.social) (2,000+ local users, federating with ~149k remote accounts). Code is at [popsolutions/mastodon](https://github.com/popsolutions/mastodon).

Why Mastodon matters for TurnKey

Mastodon is the most popular federated social network in the Fediverse, with millions of users across thousands of independent instances. It's exactly the kind of software that aligns with TurnKey's philosophy: self-hosted, open source, and giving users control over their own infrastructure.

The demand for easy Mastodon deployment is significant. Most people currently rely on Docker Compose or manual installation, both of which require ongoing maintenance expertise. A TurnKey appliance changes that equation entirely — download, boot, configure domain and admin at firstboot, done.

What we built

The appliance includes:

• Mastodon v4.5.8 (latest stable) installed from upstream source
• Ruby 3.4.7 via rbenv with jemalloc (using our new common Ruby vertical)
• Node.js 20 LTS via n (common nodejs vertical)
• PostgreSQL 17 (common pgsql vertical)
• Redis for caching and Sidekiq background jobs (new common Redis vertical)
• Nginx reverse proxy with WebSocket support for the streaming API
• Systemd services for mastodon-web, mastodon-sidekiq, mastodon-streaming
• Certbot for Let's Encrypt SSL
• Firstboot inithook that configures domain, admin email, admin password, and generates all required secrets (SECRET_KEY_BASE, OTP_SECRET, Active Record encryption keys)
• IPv6-first upstream blocks in Nginx

Common verticals: the bigger story

While building this appliance, we identified a significant maintainability problem in common: Ruby setup was hardcoded inside conf/rails, making it impossible for non-Rails Ruby applications (Mastodon, Redmine, future apps) to reuse it. This is the same pattern as if PHP configuration were locked inside a WordPress-specific script.

We created two new verticals in common (branch: [dev.19.04-refactor](https://github.com/marcos-mendez/common/tree/dev.19.04-refactor)):

Ruby vertical (plans/turnkey/ruby, conf/ruby, overlays/ruby/):

• Installs rbenv + ruby-build to /usr/local/rbenv with jemalloc support
• conf/ruby accepts RUBY_VERSION variable — appliances set the version they need
• overlays/ruby/etc/profile.d/rbenv.sh — system-wide rbenv availability for all users
• overlays/ruby/usr/local/bin/tkl-upgrade-ruby — runtime helper for upgrading Ruby in deployed appliances (reads .ruby-version, updates ruby-build definitions, compiles with jemalloc + parallel make, optional cleanup of old versions)
• plans/turnkey/rails refactored to #include <turnkey/ruby> instead of duplicating deps

This follows exactly the same pattern as PHP/LAMP separation.

Redis vertical (plans/turnkey/redis, conf/redis):

• Sane defaults: localhost bind, systemd supervision, allkeys-lru eviction policy
• Any appliance needing Redis (Mastodon, NextCloud, Odoo, Superset) can now #include <turnkey/redis> and COMMON_CONF += redis

With these verticals, the Mastodon appliance's plan/main is clean:

#include <turnkey/ruby>
#include <turnkey/postgresql>
#include <turnkey/nodejs>
#include <turnkey/redis>
nginx
certbot
...

And conf.d/main simply sets RUBY_VERSION=3.4.7 and lets the common vertical handle everything else. No duplicated rbenv installation, no hardcoded paths, no version-specific hacks.

The bigger vision: TKL as a decentralized microservices platform

This Mastodon appliance is a self-contained, single-node deployment — and for most instances, that's exactly right. But for those who need to scale, TurnKey has a unique opportunity that no one else is seizing.

Today, if you want to scale Mastodon (or any modern web application), the industry answer is: "use Kubernetes." That means learning a massive orchestration platform, dealing with container images pulled from random registries with unknown provenance, writing YAML manifests, managing Helm charts, debugging networking between pods — all to achieve something conceptually simple: run PostgreSQL on one machine, Redis on another, object storage on a third, and the application itself on a fourth.

TurnKey can solve this without any of that complexity. The pieces are almost all there:

• PostgreSQL appliance with native Master/Slave replication — spin up a turnkey-postgresql LXC configured as primary, another as replica. The application connects to the primary for writes, replicas for reads. No container orchestration needed — just two LXCs with a firstboot inithook that asks: "Primary or Replica? If replica, what's the primary's address?"

• Redis appliance with Sentinel for automatic failover — same pattern. One primary, N replicas, Sentinel handles promotion. The application just points to the Sentinel endpoint.

• MinIO appliance for S3-compatible object storage — this is a huge gap today. Mastodon, NextCloud, GitLab, Odoo — they all support S3-compatible storage for media/attachments. A turnkey-minio appliance with erasure coding across multiple LXCs would give people production-grade object storage without AWS, without Docker, without complexity.

• The application appliance (Mastodon, NextCloud, Odoo, etc.) configured to point to external PostgreSQL, Redis, and S3 endpoints instead of localhost.

This is decentralized microservices without Kubernetes. Each component is a proper TurnKey appliance — auditable, reproducible, built from source on Debian, with firstboot configuration, Webmin management, TKLBAM backup, and all the TurnKey infrastructure that already exists. The operator deploys LXCs on Proxmox, answers a few firstboot questions, and has a production-grade distributed architecture.

Why this matters:

1. No container supply chain risk. Every component is built by TKLDev from Debian packages and upstream source. No pulling random images from Docker Hub. No trusting that someone's Dockerfile doesn't have a cryptocurrency miner in layer 47.

2. No orchestration complexity. Proxmox already manages LXCs beautifully. You don't need Kubernetes, Nomad, or Docker Swarm to run PostgreSQL on a different machine than your application. You need two LXCs and a network connection.

3. Operational sovereignty. Organizations — especially cooperatives, public institutions, NGOs, and companies in jurisdictions with data sovereignty requirements (like Brazil's LGPD and Marco Civil da Internet) — can run their entire stack on their own hardware, with full visibility into every component, without depending on cloud providers or opaque container registries.

4. Incremental scaling. Start with a single all-in-one Mastodon appliance. When you outgrow it, spin up a separate PostgreSQL appliance, point Mastodon at it, done. Add a Redis replica when you need it. Add MinIO when media storage grows. No migration to a completely different deployment paradigm — just adding LXCs.

5. Real engineering instead of duct tape. Docker Compose files for production Mastodon are held together with environment variables, volume mounts, and prayers. A TurnKey appliance is a proper system — services managed by systemd, configuration in standard paths, logs in standard places, upgrades via package management and tested scripts.

We're not proposing to build all of this tomorrow. But the Mastodon appliance — together with the Ruby and Redis verticals in common — is the first concrete step. The pattern we established (modular verticals in common, clean appliance plan files, firstboot inithooks that generate secrets) scales directly to PostgreSQL replication appliances, Redis Sentinel appliances, and MinIO appliances.

At POPSOLUTIONS, we're building exactly this infrastructure for our cooperative hosting platform. We run a 12-node Proxmox cluster on Huawei E9000 blades in our own datacenter in Barueri, SP, Brazil. We've been hosting Odoo since 2013 and are expanding into federated services (Mastodon, XMPP, Matrix). The TurnKey appliance model is the foundation we're betting on — not Docker, not Kubernetes, not "cloud native" buzzwords. Proper systems engineering, reproducible builds, and digital sovereignty.

Production validation

This isn't theoretical. POPSOLUTIONS runs [organica.social](https://organica.social) on the same Mastodon v4.5.8 + Ruby 3.4.7 + PostgreSQL + Redis stack described above, serving 2,000+ local users and federating with ~149k remote accounts, from our own datacenter. The upgrade from 4.4.3 to 4.5.8 (which included a Ruby version bump from 3.3.x to 3.4.7) was exactly the real-world scenario that motivated creating tkl-upgrade-ruby — it codifies the manual process we went through.

We plan to scale production Mastodon hosting as a service through our cooperative ([pop.coop](https://pop.coop)), and this appliance is the foundation for that. Having a reproducible, TKLDev-built image means we can deploy consistent instances for multiple clients with confidence.

Build details

• TKLDev: 19.x-dev (Trixie)
• Base: Debian Trixie (testing)
• ISO size: ~1.7 GB
• Build time: ~40 minutes on 24-core machine
• Tested: chroot firstboot (secrets generation, admin account creation, .env.production configuration)

What's next

• Full VM/LXC boot test on Proxmox
• mastodon-upgrade helper script for in-place version upgrades
• TKLBAM profile
• Elasticsearch integration (optional, for full-text search)
• S3-compatible object storage configuration for media
• PostgreSQL appliance with native replication (Master/Slave firstboot)
• Redis appliance with Sentinel support
• MinIO appliance for S3-compatible object storage
• External service configuration in Mastodon (point to separate PG/Redis/S3 appliances)

Code

• Appliance: https://github.com/popsolutions/mastodon
• Common verticals: https://github.com/marcos-mendez/common/tree/dev.19.04-refactor

We're ready to open PRs against common and turnkeylinux-apps whenever the approach makes sense to you, @JedMeister. Happy to adjust anything.

One more thing — Fediverse!

@JedMeister, @OnGle — do you have accounts on the Fediverse? We'd love to connect with you there as well. The TurnKey community would benefit from having a presence on federated social networks, and we're happy to host accounts for TurnKey maintainers on organica.social if you're interested. It seems fitting that the people who help make Mastodon easy to deploy should also be part of the network it creates. 🙂

---

Marcos Méndez
[POPSOLUTIONS Cooperative](https://pop.coop)
[@marcos@organica.social](https://organica.social/@navigator)

[marcos-mendez]

Hey @JedMeister and @OnGle

To make your lives easier, I've put two test images up for you to grab:

• ISO: http://[2804:710:d0:5:be24:11ff:fed1:5794]:8080/debian-13-turnkey-mastodon_19.0-4_amd64.iso
• LXC/Proxmox: http://[2804:710:d0:5:be24:11ff:fed1:5794]:8080/debian-13-turnkey-mastodon_19.0-4_amd64.tar.gz

Note: links are IPv6-only (hosted on our tkldev). If you need IPv4 access, let me know and I'll find another way to share.

---

A few things worth knowing before you test:

Dependencies — pending PRs

This appliance depends on three PRs that are still open. Without them merged, builds will fail or behave incorrectly:

• fix: Python 3.13 + Debian Trixie migration (deb822, product.mk) fab#40 — Python 3.13 + Trixie migration (deb822, product.mk)
• Add dual-stack IPv4/IPv6 network support for TKL v19 common#338 — dual-stack IPv4/IPv6 (dhcpcd), apache-ssl fix
• Add IPv6 support to confconsole network detection and display confconsole#101 — IPv6 detection and display support

Password complexity

Mastodon enforces strict password requirements (length + complexity). I had to tune the inithook and confconsole password generation to meet these requirements. Tried to keep it as modular as possible, but given my limited experience with TKL internals compared to yours, there are likely rough edges.

Initialization

The appliance works well with turnkey-init after first boot. However, I wasn't able to get the inithook to trigger automatically — it still requires manual invocation. Any guidance here would be appreciated.

Admin account

After initialization, the sysadmin needs to grant themselves Owner role manually:

su -s /bin/bash mastodon -c "
cd /home/mastodon/live && \
RAILS_ENV=production bin/tootctl accounts modify YOUR_USERNAME --role Owner
"

Build time

Sharing pre-built images because building from scratch takes well over 40 minutes even on a 24-core/36GB RAM machine. Mastodon is by far the heaviest appliance in the TKL catalog at ~1.8GB — but the growth potential for federated social infrastructure justifies it.

Looking forward to your honest feedback.

Best,
Marcos