Self-hosting

Supported operating systems

Distro	Versions	Container runtime
Ubuntu	20.04+	Docker (auto-installed) or Podman
Debian	11+	Docker (auto-installed) or Podman
Fedora	38+	Docker or Podman (auto-installed)
RHEL / Rocky / AlmaLinux	8+	Docker or Podman (auto-installed)
CentOS Stream	9+	Docker or Podman (auto-installed)
openSUSE Leap / Tumbleweed	latest	Docker or Podman (auto-installed)
Arch Linux	rolling	Docker or Podman (auto-installed)

Requirements: systemd, x86_64 or arm64, kernel ≥ 5.4. Alpine and non-systemd distros are not supported.

Prerequisites

• A supported Linux distro (see above)
• At least 5 GB free disk space (images + k3s + data)
• A public domain with NS records pointing to this server’s public IP (required before TLS certificates can be issued)
• Ports 80, 443, 53 (TCP+UDP), and 3478/UDP open in your firewall and not in use by other services on the host (port 53 conflicts with systemd-resolved on Ubuntu 22.04+ — the installer will warn you)
• Root / sudo access

Install

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/meshploy/meshploy/main/get.sh)"

The script installs Docker (if needed), downloads Meshploy to /opt/meshploy, walks you through an interactive setup (domain, IP, secrets), and starts the full stack. Select Master for the gateway node or Worker to join an existing mesh.

DNS setup

Point your domain’s NS records to the gateway’s public IP before running the install. Meshploy runs its own CoreDNS authoritative server — no third-party DNS provider needed.

# At your registrar, delegate a subdomain to the gateway
meshploy.example.com  NS  <gateway-public-ip>

After install, verify:

dig @<gateway-public-ip> app.meshploy.example.com A

Managing your installation

All operations go through get.sh — no Docker Compose commands needed.

Command	What it does
sudo bash -c "$(curl -fsSL URL)"	Fresh install
sudo bash -c "$(curl -fsSL URL)" _ --reinstall	Update images and config, preserve database and TLS certs
sudo bash -c "$(curl -fsSL URL)" _ --reinstall --wipe-data	Full reinstall from scratch, wipes database and TLS cert cache
sudo bash -c "$(curl -fsSL URL)" _ --uninstall	Remove Meshploy (interactive)
sudo bash -c "$(curl -fsSL URL)" _ --cli-only	Install or update the meshploy CLI binary only — safe on existing nodes

Replace URL with https://raw.githubusercontent.com/meshploy/meshploy/main/get.sh

TLS cert cache: Caddy stores Let’s Encrypt certificates in a Docker volume. --reinstall always preserves this volume to avoid hitting rate limits (5 certs per domain per week). Use --wipe-data only when you genuinely need a clean slate.

---

Local Development

Prerequisites

• Go 1.22+
• Node.js 20+
• PostgreSQL 15+
• Docker

1. Clone and configure

git clone https://github.com/meshploy/meshploy
cd meshploy
cp .env.example .env

Edit .env:

DATABASE_URL=postgres://user:password@localhost:5432/meshploy?sslmode=disable
JWT_SECRET=your-long-random-secret
ENCRYPTION_KEY=exactly-32-characters-here!!!!!   # openssl rand -hex 16

2. Start PostgreSQL

docker compose -f deploy/docker-compose.dev.yml up -d

This starts only PostgreSQL on port 5432. Headscale, CoreDNS, Caddy, and the registry are not needed for local development — the API and frontend work without them.

3. Run the API

cd apps/api && go run main.go

API at http://localhost:4000 · OpenAPI docs at http://localhost:4000/docs

4. Run the Proxy

cd apps/proxy && go run main.go

5. Run the Web dashboard

cd apps/web && npm install && npm run dev

Dashboard at http://localhost:5173

---