The official Docker images are the right default for most self-hosted installs. They are stable, predictable, and maintained by the Seed team. But they intentionally represent what the core project has already accepted and released. If you want to try a new feature, tune the interface for your own publishing workflow, add an integration, or experiment with a behavior that may never belong in the default product, the official images are not enough.

Running from your own fork turns open source from “I can read the code” into “I can shape the software I use.” Your site becomes a place where you can test ideas in production for yourself, without asking the core team to prioritize them first. Later, if an idea proves useful, you can upstream it as a pull request; if it remains personal, it can simply stay in your fork.

This guide shows how to run a self-hosted Seed site from your own fork instead of the official Docker images. The setup keeps your fork's main branch rebased on upstream Seed, builds your own Docker images with GitHub Actions, publishes them to GHCR, and lets your server auto-update from those images.

The result is a repeatable deployment loop:

1. develop a change in your fork;

2. rebase your fork on upstream main;

3. build and publish fork-owned Docker images;

4. let your server pull and run those images;

5. roll back to an immutable SHA tag if something goes wrong.

The examples below use:

• Fork: horacioh/seed

• Upstream: seed-hypermedia/seed

• Deployment branch: main

• Web image: ghcr.io/horacioh/seed-web:main

• Site/daemon image: ghcr.io/horacioh/seed-site:main

• Site domain: https://seed.horacioh.com

Replace those values with your own GitHub username, fork, and domain.

Create a fork of the Seed repository and add the upstream remote locally:

git remote add upstream https://github.com/seed-hypermedia/seed.git
git remote add myfork git@github.com:<your-user>/seed.git

Use your fork's main branch as the deployment branch. Your changes should live as commits on top of upstream main.

To manually rebase your fork:

git fetch upstream main
git fetch myfork main
git switch main
git rebase upstream/main
git push --force-with-lease myfork main

Do not auto-resolve rebase conflicts. If conflicts happen, resolve them manually, run checks, and push with --force-with-lease only after the branch is healthy.

Add a GitHub Actions workflow that keeps your fork's main branch rebased on upstream main.

Important details:

• Checkout your fork's main.

• Add seed-hypermedia/seed as upstream.

• Rebase onto upstream/main.

• Push with --force-with-lease.

• If the rebase conflicts, let the workflow fail.

• If you trigger an image build from this workflow, explicitly target your fork with --repo <your-user>/seed.

Example dispatch command after a successful rebase:

gh workflow run custom-ghcr-images.yml --repo <your-user>/seed --ref main

Branch protection note: this workflow needs permission to force-update main. Configure branch protection accordingly, or use a separate deployment branch instead.

The simplest artifact store is GitHub Container Registry (GHCR). Public GHCR images are free and Docker-native.

Create a custom image workflow based on Seed's release-docker-images.yml, but change:

• Trigger: run on pushes to your fork's main.

• Tag: publish main instead of latest.

• Registry target: publish to ghcr.io/<your-user>/... instead of Docker Hub.

Publish both images from the same commit:

ghcr.io/<your-user>/seed-web:main
ghcr.io/<your-user>/seed-site:main

Also publish immutable rollback tags:

ghcr.io/<your-user>/seed-web:sha-<commit-sha>
ghcr.io/<your-user>/seed-site:sha-<commit-sha>

For Horacio's fork, the image refs are:

ghcr.io/horacioh/seed-web:main
ghcr.io/horacioh/seed-site:main

Why publish both web and site? Because frontend and daemon changes can move together after upstream rebases. Running a custom web image against an unrelated official daemon image can create compatibility issues.

The deploy compose file should allow full image refs. Instead of hardcoding only official images:

image: seedhypermedia/web:${SEED_SITE_TAG:-latest}
image: seedhypermedia/site:${SEED_SITE_TAG:-latest}

use overridable refs:

image: ${SEED_WEB_IMAGE:-seedhypermedia/web:${SEED_SITE_TAG:-latest}}
image: ${SEED_SITE_IMAGE:-seedhypermedia/site:${SEED_SITE_TAG:-latest}}

Your deploy config should store:

{
  "deploy_url": "https://raw.githubusercontent.com/<your-user>/seed/main/ops",
  "compose_url": "https://raw.githubusercontent.com/<your-user>/seed/main/ops/docker-compose.yml",
  "release_channel": "main",
  "web_image": "ghcr.io/<your-user>/seed-web:main",
  "site_image": "ghcr.io/<your-user>/seed-site:main"
}

This keeps seed-deploy upgrade and seed-deploy deploy pointed at your fork instead of switching back to the official deploy script.

On the server, run the deploy script from your fork:

curl -fsSL https://raw.githubusercontent.com/<your-user>/seed/main/ops/deploy.sh | \
  SEED_DEPLOY_URL=https://raw.githubusercontent.com/<your-user>/seed/main/ops sh

For an existing install, back it up first:

seed-deploy backup

Then reconfigure it with your fork deploy source:

SEED_DEPLOY_URL=https://raw.githubusercontent.com/<your-user>/seed/main/ops \
  seed-deploy deploy --reconfigure

Use values like:

domain: https://your-seed-site.example.com
network: mainnet
release_channel: main
web_image: ghcr.io/<your-user>/seed-web:main
site_image: ghcr.io/<your-user>/seed-site:main

For Horacio's deployment:

domain: https://seed.horacioh.com
network: mainnet
release_channel: main
web_image: ghcr.io/horacioh/seed-web:main
site_image: ghcr.io/horacioh/seed-site:main

If your GHCR packages are private, log in from the server before deploying:

echo "$GHCR_TOKEN" | docker login ghcr.io -u <your-user> --password-stdin

Public GHCR packages do not need Docker login.

Run a deploy:

seed-deploy deploy

Verify the running containers:

seed-deploy doctor
docker inspect seed-web --format '{{.State.Status}} {{.Config.Image}}'
docker inspect seed-daemon --format '{{.State.Status}} {{.Config.Image}}'

Expected output should include your GHCR images:

running ghcr.io/<your-user>/seed-web:main
running ghcr.io/<your-user>/seed-site:main

Check logs if needed:

seed-deploy logs web
seed-deploy logs daemon
seed-deploy logs proxy

The deploy tool installs cron jobs that periodically run upgrade and deploy. Check them with:

crontab -l | grep seed-

To test auto-update:

1. Push a small change to your fork's main.

2. Wait for the GHCR image workflow to publish new images.

3. Wait for cron, or trigger deploy manually:

   seed-deploy deploy

4. Confirm the image IDs or container start times changed:

   docker inspect seed-web --format '{{.Image}} {{.State.StartedAt}}'
   docker inspect seed-daemon --format '{{.Image}} {{.State.StartedAt}}'

Because the workflow publishes immutable sha-<commit> tags, rollback is just a config change.

Pick a known-good commit SHA and set both images to matching tags:

{
  "web_image": "ghcr.io/<your-user>/seed-web:sha-<commit-sha>",
  "site_image": "ghcr.io/<your-user>/seed-site:sha-<commit-sha>"
}

Then deploy:

seed-deploy deploy
seed-deploy doctor

Return to the moving channel by setting both images back to :main.

The complete flow is:

1. Keep your fork's main rebased on upstream main.

2. Build and publish web and site images from your fork to GHCR.

3. Configure your server to use your fork's deploy source.

4. Configure full GHCR image refs for both services.

5. Let seed-deploy cron pull new :main images automatically.

6. Use sha-<commit> tags when you need a pinned rollback.