ubuntu-post-install/docs/vps-sizing-recommendations.md

VPS sizing & recommended services

Reference notes from sizing this repo's services against real VPS plans. Not project documentation for contributors — a planning record for picking services against a given vCPU/RAM/disk budget.

How to size a VPS for this repo's services

For this class of self-hosted workload (web apps, a PBX, a few Docker containers — no video transcoding, no ML inference), RAM is almost always the binding constraint, not CPU or disk. CPU only matters once something is transcoding video, mixing many conference audio streams, or running local AI inference — none of which apply to most services in this repo. Disk only matters once local media storage is involved.

Rough per-service RAM budget, idle:

Kind of service	~RAM
OS + Docker daemon baseline	300-500MB
JVM apps (Traccar, UniFi)	350-500MB
App with its own Postgres/MariaDB (Mattermost, Nextcloud, Immich)	+150-250MB for the DB alone, on top of the app
Lightweight single-binary apps (Go/Rust — ntfy, vaultwarden, wg-easy, homebox, actualbudget, syncthing, portainer, coturn)	20-150MB each
Headless-Chrome-backed apps (archivebox, changedetection's JS mode)	300-500MB+

Rules of thumb:

• Keep at least 25-30% of total RAM free at idle for burst load (image pulls, log bursts, concurrent call/session spikes).
• A swapfile is cheap insurance and is now a default for every install, not just Asterisk droplets — base.sh calls lib/common.sh's ensure_swapfile() unconditionally, which offers a 2GB swapfile any time RAM is ≤4096MB and none exists yet (services/asterisk.sh also calls it directly for the standalone-run case, so it's covered either way).
• Sharing one coturn instance (services/coturn.sh) instead of letting each WebRTC-capable service (Asterisk, Mattermost) embed its own saves a container per consumer and — more importantly — avoids relay-port collisions between them.

Tier 1 — ~1 vCPU / 1GB RAM / 25GB SSD

Example: DigitalOcean Basic, $6/mo.

This is tight enough that Docker's own daemon overhead is already a meaningful fraction of the box. Pick one purpose, not a stack:

• Option A — Asterisk only. Asterisk + the shared coturn service fits comfortably per this repo's own droplet-sizing notes (services/asterisk.sh README section) — a swapfile is added automatically (RAM ≤4GB, see above), and this plan is "fine for a couple of extensions and light personal use."
• Option B — a lightweight utility box. Caddy + CrowdSec + NetBird (all near-zero RAM) plus at most one or two of the smallest apps (ntfy, vaultwarden, wg-easy) — total comfortably under 500MB.

Avoid on this tier: anything with its own database (Mattermost, Traccar, Nextcloud), more than one substantial app, media/AI/gaming services. There's no headroom for a second heavy thing once the first one is running.

Tier 2 — 4 vCores / 4GB RAM / 120GB NVMe

Example: IONOS VPS M+, $11/mo. This is the tier actually planned out in detail — see the recap below.

What I was planning for the IONOS 4 vCPU / 4GB / 120GB box

Reconstructed from the sizing conversation, in the order decisions were made:

Core stack (the original ask):

• caddy — reverse proxy / HTTPS
• crowdsec — intrusion prevention
• asterisk — PBX, using the shared coturn service (not embedded)
• mattermost × 2 — genuinely isolated instances (separate dir/containers/DB per instance), both sharing the one coturn service — this required merging PR #265 (claude/droplet-capacity-assessment-s2voix), which extracted coturn into services/coturn.sh and added real multi-instance support to services/mattermost.sh; merged into main at commit 6151ede
• traccar — GPS tracking

Validated call load: up to 9 concurrent Asterisk calls, at most 1 Mattermost call at a time, 0 screen share. Comfortably within budget — no transcoding/conferencing/heavy-video load in this profile, so CPU has large margin and RAM sits around 2.0-2.7GB idle with the core stack alone.

Utility adds, agreed:

• ntfy, wg-easy, homebox, mealie

Explicitly declined: vaultwarden, portainer, syncthing, actualbudget (dropped to make room for WordPress — see below)

Remote / cross-VLAN access: NetBird — hosted control plane (not self-hosted), client-only, with its embedded SSH server enabled (--allow-server-ssh, JWT/OIDC-based user auth, no user SSH keypair to manage). Already implemented in services/base.sh (_base_setup_netbird()) as part of every box's base install — nothing further to build for this. Chosen over self-hosting a WireGuard mesh once it was clear that (a) a hub-routed WireGuard design makes the VPS a single point of failure for inter-peer connectivity specifically, not just VPS access, and (b) a different person ever needing access means hand-editing authorized_keys on every box instead of revoking centrally — NetBird's actual value here is solving both, not just being "zero-config."

wg-easy's role, narrowed: kept in the utility-add list, but as a local-VLAN WireGuard testing ground, not the primary remote-access path — that's NetBird's job. The hub-routed peer mesh (WG_ALLOWED_IPS=0.0.0.0/0 by default, so any two enrolled peers already reach each other through the VPS with no per-pair config) plus a sync-ssh-aliases.sh companion script (reads peers straight off the live WireGuard interface via wg show, generates ~/.ssh/config Host aliases) is already built and pushed (claude/vps-capacity-assessment-r57vw3, commit 4a0ec63).

Confirmed: audiobookshelf on the VPS with HTTPS via Caddy, but pointing it at a home-hosted library over a VPN tunnel (NetBird or wg-easy, whichever link reaches that box) instead of storing audiobooks locally — services/audiobookshelf.sh already just bind-mounts a host path, so this means mounting a network share from that tunnel at the mount point instead of a local directory. Avoids the disk/CPU tradeoffs of a local media library; real bandwidth depends on home upload speed, which wasn't checked.

Music: emby, music-only — not lyrion. lyrion (LMS/Squeezebox) was floated first since it's a purpose-built, well-regarded music server, but ruled out for two protocol-level reasons neither Caddy nor Authelia can paper over: its own web-UI auth is one shared server-wide password (no per-user accounts), and its player protocol (SlimProto, port 3483) is raw TCP with no authentication of its own, so Authelia's HTTP-only forward_auth can't gate it at all. emby (already registered in this repo, media category) solves both — real per-user accounts with per-library access restriction, and every client protocol it uses is HTTP, so Caddy fronts all of it cleanly. services/emby.sh now has a music-only mode (prompts for this, defaults the folder to ~/music, and the generated README walks through adding only a Music library plus the Dashboard → Users → Access per-user restriction steps in Emby's own setup wizard). Tradeoff accepted knowingly: Emby is a generalist media server, not a purpose-built one — it lacks LMS's music-specific depth (its lyrics fetching, its many audio-focused plugins). Since there's no hardware Squeezebox tie-in to preserve, that tradeoff was fine to make.

Emby subsequently dropped from the near-term plan — traded off for WordPress capacity (below) rather than run alongside it. services/emby.sh's music-only mode is still there and ready whenever there's headroom for it again; it just isn't part of the current baseline.

WordPress — confirmed, 2 sites (settled), light traffic, ecommerce-capable. services/wordpress.sh (new): multi-site from the start, every site named, each with its own dedicated MariaDB container (same pattern as services/nextcloud.sh) — not a shared instance. Started as a shared-MariaDB design (same resource-sharing idea as coturn) but switched to dedicated per-site after weighing it against backup/restore: Kopia's generic backup (services/backup.sh) stops a service's container to snapshot it, so a shared instance would back up — and would have to be restored — as one unit covering every site at once, not one site independently. Dedicated per-site costs more RAM (a full MariaDB container each, ~100-150MB, instead of one instance amortized across sites) in exchange for real isolation: each site's database backs up and restores completely independently. Separate databases were always required regardless of which model — WordPress's schema uses generic table names (wp_posts, wp_options, etc.), so two installs sharing one database with the same table prefix would collide — the shared-vs-dedicated choice was only ever about the container/process, never about the data being mixed. wp-cli automates the initial install (title, admin account) so there's no per-site browser setup wizard, and PHP limits are pre-tuned (256M memory, 64M uploads) for WooCommerce specifically since "possible ecommerce" was part of the ask.

Explicitly out of scope for this box (wrong fit, not "can't run"):

• Local media servers storing media on the VPS (jellyfin, immich, lyrion, and emby/audiobookshelf without the home-library-over-VPN approach used above) — disk-hungry, and transcoding CPU load risks contending with active calls.
• AI stacks (ai-stack, ai-gpu, iopaint, paintplus) — need real VRAM/RAM most VPS plans don't have.
• Gaming (minecraft, wolf, wolf-pair, sunshine, kyber-*) — CPU/RAM heavy; cloud-gaming ones need GPU passthrough.
• Cameras/NVR (frigate*, sky-cam) — needs real camera feeds; doesn't make sense geographically on a VPS.
• nextcloud + onlyoffice — the combined PHP+DB+office-suite stack alone would likely eat most of the remaining headroom.
• unifi — only worth ~300-500MB of Java if actually managing Ubiquiti gear from this box.
• SSH ProxyJump/bastion-hop chaining for reaching genuinely isolated (CGNAT, no local peer) boxes — a good idea in principle, parked for later since NetBird already covers the current need.

Final RAM budget for the IONOS box (settled baseline, no Emby, no actualbudget, idle)

Service	~RAM
OS + Docker baseline	~400MB
Caddy	~30MB
CrowdSec	~150MB
coturn (shared)	~40MB
Asterisk	~100MB
Mattermost × 2 (app+Postgres each)	~1200MB
Traccar (JVM)	~425MB
NetBird client	~35MB
ntfy, mealie	~225MB combined
WordPress × 2 sites (app ~80MB + dedicated MariaDB ~120MB each)	~400MB
Total	~3.00GB

Leaves roughly ~1.09GB headroom (~27%) out of 4GB — back into the ideal 25-30% range, between dropping actualbudget (~115MB) and settling on 2 sites instead of 4 (dedicated-per-site MariaDB's cost scales with site count, so this was the single biggest lever). With the swapfile now automatic (ensure_swapfile, see above) there's real insurance on top of that margin, not instead of it. wg-easy, homebox, and audiobookshelf from earlier in this doc aren't included in this specific table — add them back in at ~25MB, ~125MB, and ~200MB respectively if/when they're actually deployed alongside this baseline. Deploy incrementally and check free -h / docker stats against this table rather than trusting it blindly — each line carries real estimate uncertainty, and they're stacked close enough to the ceiling that it's worth confirming. If real usage runs higher than estimated, the two Mattermost instances (~1.2GB combined) are the single biggest lever to reconsider.

Tier 3 — 6 vCores / 8GB RAM / 240GB NVMe

Example: IONOS VPS L+, $21/mo.

What I was planning for the 6vCPU / 8GB / 240GB box

A much larger multi-instance spread than the Tier 2 box, sized against this repo's multi-instance retrofit (services/*.sh instance-selection pattern, see CLAUDE.md's "Multi-instance services" section) plus its port-collision scanning (CLAUDE.md's "Port collision avoidance" section). The instance counts below aren't arbitrary — a few of them ran into real limits in the codebase as it exists today, not just RAM ceilings.

Not actually possible as "2x" — singleton-by-design, no multi-instance support exists:

• asterisk — one PBX per box. Fixed SIP port 5060, one AMI, one DigitalOcean-layout detection, one extension plan. A second instance would fight the first over the same SIP/RTP ports; there's no instance-suffix logic to make that not collide.
• security-dashboard — runs natively (not Docker), reads one Asterisk's security log and talks to one CrowdSec via cscli. There's no second log/CrowdSec on the box to point a second copy at.
• sms-inbound — also native, tied to one Asterisk + one pstn-trunk's DID-ownership mapping. Same story as security-dashboard.

All three stay at 1x on this box regardless of how the rest of the stack is sized.

Dropped from this plan, not attempted:

• changedetection × 2 — only got the port-collision-scanning pass this session, not the full multi-instance retrofit (no directory-suffix logic), so a second install would collide with the first's ~/docker/changedetection. It also runs a dedicated Playwright/Chrome sidecar per instance (~300-500MB each) — expensive for what would be a head-to-head with retrofitting it.
• magicmirror × 6 — its existing multi-instance pattern (a different, earlier design than the rest of the repo: upfront instance count, not incremental) is hardcoded to 1-3 instances. Six would need a code change, not just a bigger box, and 6 dashboard instances (~900MB) was a lot of RAM for the value versus the rest of this stack.

Screen-sharing tool — RustDesk over MeshCentral. Both services/rustdesk.sh and services/meshcentral.sh have real multi-instance support. RustDesk's relay (hbbs/hbbr) is a lightweight Rust binary that doesn't decode video itself — screen-share traffic goes peer-to-peer between clients, the relay just proxies — so it costs ~40MB per instance versus MeshCentral's full Node.js app per instance (~150-250MB). Chose RustDesk for the RAM headroom; MeshCentral remains the pick if agent-based remote management (not just screen viewing) matters more than the RAM difference.

Everything else scales the same way it does on the Tier 2 box — same shared coturn, same NetBird base install, same dedicated-per-instance database pattern (Traccar's own datastore, Joplin/WordPress's dedicated Postgres/MariaDB per instance, per CLAUDE.md's backup-isolation reasoning). traccar settled at 1x (not 2x) specifically to buy back RAM — JVM apps don't shrink well when duplicated (~425MB is mostly fixed heap overhead, not data-proportional), so a second instance was the highest-RAM, lowest-value item once Mattermost stayed at 3x.

Emby stays music-only-plus-everything (2 instances, one restricted to a Music library per CLAUDE.md's per-user-access pattern, one unrestricted) — idle RAM only; if the "everything" instance serves remote clients that can't direct-play, transcoding adds real CPU plus ~200-400MB per active session, not counted in the idle table below.

No automatic swapfile on this box. ensure_swapfile() only offers one when RAM ≤4096MB — an 8GB box doesn't qualify, so unlike every Tier 1/2 box in this doc, this one has no swap unless it's added by hand.

Final RAM budget for the 6vCPU/8GB box (settled baseline, idle)

Service	Count	~RAM
OS + Docker baseline (~45-50 containers across all instances)	—	~500MB
Caddy	—	~30MB
CrowdSec	—	~150MB
coturn (shared)	—	~40MB
NetBird client	—	~35MB
Asterisk	1 (singleton)	~100MB
security-dashboard + sms-inbound	1 each (singleton)	~95MB
Mattermost (app+Postgres each)	3	~1800MB
Traccar (JVM)	1	~425MB
ntfy	2	~100MB
Mealie	2	~350MB
WordPress (dedicated MariaDB/site)	2 sites	~400MB
Actual Budget	2	~140MB
Audiobookshelf	2	~400MB
Emby (music-only + everything)	2	~450MB idle*
Filebrowser	2	~80MB
FMD	2	~100MB
Homebox	2	~250MB
Joplin (app + dedicated Postgres each)	2	~400MB
RustDesk relay	2	~80MB
Vaultwarden	2	~80MB
Total		~6.0GB

* idle only — see the Emby note above for active-transcode cost, not included here.

Leaves roughly ~2.0GB headroom (~25%) out of 8GB — right at the bottom of the ideal 25-30% range from the sizing rules of thumb above. Swapping rustdesk for meshcentral narrows that to ~1.6GB (~20%) — still workable, just tighter. CPU isn't expected to bind here (no transcoding/AI/gaming load in this mix per the "How to size" rule of thumb above), but 3 concurrent Mattermost calls, active Asterisk calls, and a RustDesk/MeshCentral session all at once is the realistic worst case worth watching, not the idle numbers in this table. Deploy incrementally and check free -h / docker stats against this table the same way as the Tier 2 box — if real usage runs higher than estimated, Mattermost (~1.8GB across 3 instances) is again the single biggest lever to reconsider.