A Seed site shows one space at a web domain. It is three containers: a Seed daemon, a Seed web app, and a reverse proxy in front of them. This guide runs those three containers on a server you control. You install the site, register a space, and look after the node from day to day.
If the site is already running and something is wrong, the first thing to check is seed-deploy doctor.
The hosted service runs sites for you under *.hyper.media. Your content and your key stay yours either way. So a hosted site can move to your own server later, and back again. An organization that wants a closed node for invited people only uses the enterprise node profile of the same script.
Goal. A site at https://example.org that publishes your space, gets TLS certificates by itself, checks for updates every ten minutes, and can be backed up with one command.
Prerequisites.
A Linux server with about 2 GB of RAM, a public IPv4 address, and ports 80 and 443 free. The deploy script needs glibc 2.25 or newer, which means Ubuntu 18.04, Debian 10, RHEL 8, Fedora 28 or Amazon Linux 2023 and later. It installs Docker and Bun if they are missing.
A domain name you control, with access to its DNS records.
The Seed desktop app with the space you want to publish, and its key. Whoever holds that key can publish to the site.
1. Point the domain at the server
At your DNS provider, add an A record for the domain. The name is @ for the root, or a subdomain such as docs. The value is the server's IP address. Do this first. The proxy asks Let's Encrypt for a certificate when it first starts, and that works only once the name leads to the server.
2. Run the deploy script
Log in as root or as a user with sudo, and run:
curl -fsSL https://deploy.seed.hyper.media | shThat URL serves the bootstrap script, which is ops/deploy.sh on the main branch of the Seed repository. (The address is run by the Seed team and can change.) You can get the script from GitHub directly if you want to read it first. The bootstrap script does four things:
It installs Docker and Bun when they are missing.
It downloads the deploy program to /usr/local/lib/seed/deploy.js.
It installs the seed-deploy command.
It starts a wizard that asks you questions.
The wizard asks:
Question | What to answer |
|---|---|
Public hostname | the full URL, |
P2P network | Mainnet, unless you are testing against the team's dev network |
Release channel | Stable ( |
Log level | Info |
Gateway mode | No, for a site that publishes one space; Yes makes the node serve every public account it learns about, like |
Agents | No, unless you want to run Seed Agents on the site itself, at |
Contact email | optional, for security notices |
The contact email is the only way a security notice reaches you. The script does not tell the Seed team about your deployment.
The script then writes the configuration, makes a Caddyfile, pulls the images and starts the containers. A first deploy ends with:
Setup complete
Your site is live at https://example.org
Registration URL:
https://example.org/hm/register?secret=…
Copy this URL and paste it into the Seed desktop app
to link your publisher account to this site.Until you register a space, the site shows a "not registered" page. seed-deploy secret prints the registration URL again.
3. Register your space from the Seed app
In the desktop app, open the space.
Choose Publish Site from the options menu at the top right.
Paste the registration URL and confirm.
This is what happens:
The app reads the site's /hm/api/config.
The app pushes the space's home document, and what belongs to it, to the site's daemon.
The site records the account and subscribes its daemon to the space. From then on it shows that account's home document at https://example.org.
Registration uses up the secret. A registered site refuses any other account. To move a site to another space:
Replace the web configuration file (web/config.json, described below) with {"availableRegistrationSecret": "<secret>"}. The secret from seed-deploy secret works.
Run seed-deploy restart, so the web app reads the file again.
Register again.
What is running
Three containers run. The compose file that the script downloads from the repository defines them.
Container | Image | Ports on the host | Role |
|---|---|---|---|
|
| 80, 443, 443/udp | TLS from Let's Encrypt, then reverse proxy |
|
| 3000 | the Seed web app: pages, the Seed API, site services |
|
| 56000, 56000/udp and 143 | the Seed daemon: storage, indexing, libp2p |
How the pieces fit together:
Routing. Caddy sends /ipfs/* to the daemon and everything else to the web app.
Agents. With agents on, a fourth container runs: seed-agents (image seedhypermedia/agents, compose profile agents, data in agents/). It answers /hm/api/apps and /hm/api/agents and everything under them, open like the rest of the site. The web app offers it as the site's app environment (SEED_AGENT_SERVER_URL). With agents off, the web app offers the hosted one.
Notify. Email notifications always go through the hosted notify service at https://hyper.media/hm/api/notify.
Private ports. The daemon's own HTTP and gRPC ports (56001 and 56002) are not published on the host. Trusted services reach them over the container network. Keep them private, and pass only the public /ipfs/* routes through the proxy.
Server mode. The Docker image turns on server mode with SEED_SERVER_MODE=true, though the compose file passes no mode flag. In server mode the daemon trusts the network it is deployed on and does not serve private content to readers without a sign-in. It does not check who may write (see daemon gRPC).
Private documents. On a site that holds private documents of the registered space, the web app passes on the visitor's sign-in token, so the daemon can allow private reads.
The daemon must be reachable from the internet:
It runs with -p2p.force-reachability-public and -p2p.no-relay. It announces /dns4/example.org/tcp/56000 and the same for QUIC. Peers connect to it directly, and so does the desktop app that publishes to the site. So the libp2p port must be open to the internet.
Host port 143 leads to the same listener, and the daemon announces it as /dns4/example.org/tcp/143. Some university networks, such as eduroam, do not allow port 56000 but allow 143 (IMAP). A Seed app on such a network reaches the site through 143. Open 143 in the host firewall too.
A host that already runs a mail server on port 143 cannot start the daemon container until one of the two moves.
Agents and code execution. Code execution in a sandbox needs /dev/kvm, which ordinary virtual servers do not have. This is true for a site and for an enterprise node. The compose file comes without it, and then agents are not offered execute. On a host with KVM, set "agents_kvm": true in config.json. The deploy then adds the device and the kvm group to the container, the way it adds /dev/dri to the daemon on a host with a GPU. See the code execution backend, and operations for running the app environment.
Everything lives under one directory, /opt/seed by default.
Path | Contents |
|---|---|
| the wizard's answers: |
| the compose file, refreshed on every deploy |
| the proxy configuration and its certificates |
| the site's web configuration: |
| resized images |
| the daemon's data directory: the SQLite database, the blob store, |
The containers run as your user, never as root. Every bind mount has the :z flag, for hosts with SELinux.
Day-to-day
The seed-deploy command manages the node.
Command | What it does |
|---|---|
| headless update: refetch the compose file, pull images if anything changed, recreate containers, prune old images; a no-op when nothing changed |
| re-run the wizard with current values as defaults |
| health: containers, disk, cron, certificate expiry, whether the site is registered |
| tail a container's logs (also |
| the registration URL; the configuration with secrets redacted |
| without redeploying |
| a |
| unpack a backup, optionally edit the configuration, deploy |
| install or remove the update jobs |
| update the deploy script itself |
| remove containers, data and configuration |
Updates. The wizard installs two cron jobs. One runs upgrade then deploy every ten minutes, so the node follows its release channel. The other removes unused images older than an hour, every hour. The deploy script itself always follows the main branch, whatever the image channel is, so fixes to the script reach every node. SEED_DEPLOY_URL and SEED_REPO_URL point the script at another source, for testing a branch.
Which version is running. https://example.org/hm/api/version returns the commit, branch and build date of both the web app and the daemon.
Testing a branch. seed-deploy --advanced adds two choices. You can choose the node directory, so a branch build with its own database migrations lives in /opt/seed-mybranch beside your main node. And you can choose an image tag. Only one node runs on a host at a time, because the container names are fixed. deploy and start refuse to replace containers that belong to another directory, and doctor warns when the two disagree.
Metrics. The compose file has a metrics profile with Prometheus and Grafana, served at https://example.org/.metrics when enabled.
Debug pages. In server mode, trusted services on the daemon's private container network can open its /debug/* pages. Keep the API ports private, and do not pass these routes through the proxy. docker exec seed-daemon gives you a shell there. seed-deploy logs daemon is usually enough.
Related setups
Enterprise node: the deploy script's second profile, for one organization, invite-only and cut off from the public network.
Custom domains: serving a site at your own domain, hosted or self-hosted, and moving a node to a new hostname.
Publishing a space to a domain: the owner's steps in the Seed app.
Self-hosting an app environment: running the app environment on its own, without the deploy script.
See also
Running Seed, the hub for operators
Sites, what a site is in the protocol: the home document's siteUrl, registration, gateways
Network, how the site's daemon syncs with the app that publishes to it
Seed API, everything your new server answers
Web app and daemon, configuration and flags in detail, and the daemon network reference, for the daemon's network flags
Keys, the key that publishes to the site
Contributing, for the ops/ deploy tooling
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime