damstack

English | Русский | Español

Your own server, set up and kept running from your Mac with one program.

You rent a server, answer a few questions, and damstack turns it into a private platform: locked down to your key, reachable through your own WireGuard network, with Nomad, Consul and Vault to run apps, certificates from Let's Encrypt, and nightly backups copied to your Mac. Then you add apps to it, such as your own mail server, with one command each.

You need to know nothing about servers. damstack asks what it needs, says what it does, and checks that the server stays the way you set it up.

What you need

• A Mac, Apple silicon or Intel, with Homebrew.
• The WireGuard app, for the private network between your devices and the server.
• A server with Ubuntu 24.04, from any provider: its IP address and the root password the provider gives you. 2 CPUs, 4 GB of memory and 20 GB of disk are enough.
• A domain whose DNS is on Cloudflare, and an API token there that may edit the DNS of that domain. Other DNS providers work too, by the name lego gives them.
• For mail: a provider that lets the server send on port 25. Many block it until you ask.

Install

brew install eugene-panin/tap/damstack
damstack

The first run checks your Mac and says what is missing and how to get it. damstack downloads the tools it runs, OpenTofu, Ansible and restic, once, and keeps them apart from anything else on your Mac. No Docker is needed.

Your first server

damstack deploy hashi

damstack asks for the address of the server, the domain of the admin pages (such as admin.example.com), your email for Let's Encrypt, the Cloudflare token, and the devices that may reach the server, such as laptop and phone. Then, once, the root password of the server, to put your SSH key there; it is not kept.

Then it runs, in about ten minutes:

1. Securing the server: a user of your own, logins with your key only, root and passwords off, a firewall, automatic security updates.
2. The platform: the WireGuard network, Consul, Vault and Nomad, Docker, a synchronized clock, and the nightly backup.
3. Traefik and the admin pages: a certificate for *.<your domain>, pages that open only through WireGuard.
4. DNS records, published for you.

Halfway, it stops to bring your Mac into the private network:

damstack tunnel show laptop

puts the configuration into the WireGuard app; on a phone, damstack tunnel show phone --qr shows a code to scan.

At the end it lists the admin pages, nomad., vault. and consul.<your domain>, and how to get their tokens:

damstack token nomad

damstack trust makes your Mac trust the certificates of the private network, so that the servers also open on their own addresses.

Apps

damstack app add mail
damstack deploy

asks what the app needs and runs it on your server. The library has mail, your own mail server with Stalwart (mailboxes for every domain, DKIM, MTA-STS, IMAP and SMTP with certificates, and the DNS records mail clients find their settings from), odoo, and the shared services apps build on: postgres, nats, seaweedfs (S3), loki, mimir and grafana. An app from a repository of your own, public or private, is added the same way.

Apps run in containers on Nomad, each with only the rights it needs, and can join the Consul service mesh: a database then lets in only the apps named in its settings, over mTLS.

An app's keys, such as the API keys of an LLM, are its secrets: asked when it is added (an optional one may be left unset), changed with damstack secret set, kept encrypted and given only to the services that use them, through Vault. A changed key restarts only those services.

On a terminal

damstack deploy shows a full-screen view: every step, the tasks of the one running and how many are left, the plan to approve before anything changes, what failed in the words of the tool that failed, and at the end every address your server serves, checked. When Nomad would change a service in a way it only takes after a restart, the plan says so and offers to restart it. --plain, a pipe or CI keep the plain lines.

Working together

Once a project is up, its state lives on its server, not on one laptop: anyone with the project can deploy it. Changes take a lock: a second deploy waits its turn and shows whose deploy it waits for. --break-glass deploys without the lock, from the state on your Mac, only to repair the server itself.

Every day

You want to	Run
See the projects and what needs you, and do the rest from there	damstack
Check that the server is as you set it up	damstack status --live
Change a setting, on a screen of sections and fields (--yaml for the file)	damstack edit
Deploy only some parts, such as one app	damstack deploy --only sauron
Deploy again, changing only what differs	damstack deploy
Deploy the apps only, the server left as it is	damstack deploy --apps-only
Give an app a key, or see which are set	damstack app keys sauron
See every secret, the riskiest first, and make the ones you pick anew	damstack secret
Add or remove a device of the private network	damstack tunnel add phone, damstack tunnel remove phone
Give a device or the server new keys	damstack tunnel rotate phone
Open a shell on the server, or run a command there	damstack ssh, damstack ssh -- uptime
See everything damstack ran	damstack history
Rename a project on your Mac	damstack rename old new

With several projects, name the one you mean, as in damstack status ovh, or make one current with damstack use ovh.

Backups

The server backs up every night: the data of Consul, Vault and Nomad, and the data of every app. damstack copies the backups to your Mac every hour while it is on; damstack backup status shows them, and the home screen warns when they get old.

Everything that brings a project back lives on your Mac. Make a recovery kit, one encrypted file with the project and its password, and keep it somewhere else, such as cloud storage, with its passphrase in your password manager:

damstack backup kit

On another Mac, damstack backup open <kit> brings the project back.

When the server is lost

Rent a new server, give its address to the project, and restore:

damstack edit          # the new address under server
damstack restore

damstack sets the new server up as it did the first one, then puts back Consul, Vault and the data of every app from the latest backup on your Mac. Your keys, tokens, mailboxes and mail are as they were.

Where things are

A project is a directory, ~/.damstack/<name>:

• stack.yaml, the one file to edit; damstack edit opens it and checks it;
• vault.yml, the secrets, encrypted; the password to it is in ~/.config/damstack/projects/<name>, outside the project;
• the state of the platform and the history of what ran.

To remove damstack: stop the hourly copy of each project with launchctl bootout gui/$(id -u)/dev.damstack.backup.<name> and delete ~/Library/LaunchAgents/dev.damstack.backup.<name>.plist; then brew uninstall damstack, and delete ~/.damstack, ~/.config/damstack and ~/.cache/damstack. Keep the first two, or a recovery kit, as long as a server of yours runs: without them nothing can manage it.

Limits today

• macOS only, and one server per project.
• The full-screen view covers the home screen, deploys, settings, the catalog, installs, apps, links, keys and secrets; the other screens of its design come in later releases.
• New releases of a platform or an app are taken by hand; there is no damstack upgrade yet.
• Tested on OVH and Google Cloud.

More

• docs/stacks.md: how a stack is written, and how to develop damstack.
• docs/design.md: where damstack is going.
• The platform: damstack-hashi; the mail app: damstack-mail.

MIT license.