Help us shape the future of Go! Take the 2026 Go Developer Survey

shed

module
v0.2.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2026 License: Apache-2.0

README

shed

shed is a self-hosted, single-server deployment platform inspired by Railway. One Go binary runs the dashboard, the API, the deploy pipeline, and an embedded Caddy reverse proxy with automatic HTTPS; Docker runs the workloads.

  • Deploy apps from GitHub repositories (Dockerfile, or Railpack when there is none) or from Docker images, automatically on push, optionally after CI passes.
  • One-click Postgres, MySQL, MongoDB, and Redis with persistent volumes.
  • Per-service variables with ${{ service.KEY }} references, domains, deployment history with rollbacks, and build and runtime logs.

See docs/design.md for how it works.

Requirements

  • Linux with Docker Engine and the buildx plugin
  • git and railpack on PATH
  • Ports 80 and 443 free for the proxy

Install

curl -fsSL https://shed.land/install.sh | sudo bash

The installer adds whatever is missing (Docker with buildx, git, railpack), asks for the dashboard domain, an optional apps base domain and ACME email, and the GitHub logins allowed to sign in, then installs the latest release, writes /etc/shed/shed.toml, starts the systemd service, and prints the setup URL and token. Run it again on an installed host to upgrade the binary and keep the config.

To run it unattended, pass the answers as environment variables (SHED_BASE_DOMAIN, SHED_ACME_EMAIL, and SHED_VERSION are optional):

curl -fsSL https://shed.land/install.sh \
  | sudo SHED_DOMAIN=shed.example.com SHED_ALLOWED_USERS=your-github-login SHED_YES=1 bash
Manual install
make build                                   # needs Go and Bun
sudo install bin/shed /usr/local/bin/shed
sudo mkdir -p /etc/shed
sudo cp deploy/shed.example.toml /etc/shed/shed.toml   # then edit it
sudo cp deploy/shed.service /etc/systemd/system/
sudo systemctl enable --now shed

Set server.url (the public dashboard URL), proxy.acme_email, and auth.allowed_users = ["your-github-login"]. Every setting can also be given as an environment variable, such as SHED_SERVER_URL. Logs go to shed.log next to the config file and to the journal.

DNS

  • An A (and AAAA) record for the dashboard host in server.url, pointing at the server.
  • For generated service domains, set proxy.base_domain (for example apps.example.com) and add a wildcard record *.apps.example.com pointing at the server.
  • Custom domains need their own record pointing at the server.

First run

  1. On first start, shed logs a one-time setup token. The installer prints it with the setup URL; otherwise find it with journalctl -u shed | grep token.
  2. Open the dashboard, enter the token, and follow the link to create the GitHub App. GitHub sends you back to shed, which stores the App's credentials.
  3. Install the App on the accounts or repositories you want to deploy.
  4. Sign in with a GitHub login listed in auth.allowed_users. There is no automatic first-user enrollment.

Development

make test                      # Go tests
cp deploy/shed.example.toml shed.dev.toml
# In shed.dev.toml: url = "http://localhost:5173", a writable data.dir, and
# proxy.enabled = false.
make dev                       # runs shed with shed.dev.toml
cd web && bun run dev --port 5173 --strictPort  # dashboard with hot reload

Directories

Path Synopsis
cmd
shed command
Command shed runs the shed deployment platform: the dashboard, the API, the deploy pipeline, and the reverse proxy, in one process.
 Command shed runs the shed deployment platform: the dashboard, the API, the deploy pipeline, and the reverse proxy, in one process.
internal
api
Package api serves shed's HTTP interface: the JSON API under /api, the server-sent event log streams, the GitHub App setup flow and webhook, and the dashboard single-page app.
 Package api serves shed's HTTP interface: the JSON API under /api, the server-sent event log streams, the GitHub App setup flow and webhook, and the dashboard single-page app.
auth
Package auth implements authentication: GitHub sign-in handlers, cookie sessions, and middleware that guards API routes, plus an OAuth 2.1 authorization server that lets agents (MCP clients) act for a signed-in user with bearer tokens.
 Package auth implements authentication: GitHub sign-in handlers, cookie sessions, and middleware that guards API routes, plus an OAuth 2.1 authorization server that lets agents (MCP clients) act for a signed-in user with bearer tokens.
backup
Package backup backs up and restores the data of shed's services and shed's own database.
 Package backup backs up and restores the data of shed's services and shed's own database.
build
Package build clones a Git commit and builds a Docker image from it, using the repository's Dockerfile when there is one and Railpack otherwise.
 Package build clones a Git commit and builds a Docker image from it, using the repository's Dockerfile when there is one and Railpack otherwise.
catalog
Package catalog describes the database templates shed can provision: image, port, data directory, and default variables.
 Package catalog describes the database templates shed can provision: image, port, data directory, and default variables.
config
Package config loads shed's configuration.
 Package config loads shed's configuration.
control
Package control holds shed's operations on projects, services, deployments, variables, domains, volumes, backups, metrics, and updates: the rules every interface to shed shares.
 Package control holds shed's operations on projects, services, deployments, variables, domains, volumes, backups, metrics, and updates: the rules every interface to shed shares.
deploy
Package deploy runs shed's deployment pipeline.
 Package deploy runs shed's deployment pipeline.
docker
Package docker is a thin wrapper over the Docker Engine API client that exposes only the operations shed needs.
 Package docker is a thin wrapper over the Docker Engine API client that exposes only the operations shed needs.
github
Package github integrates shed with a single GitHub App.
 Package github integrates shed with a single GitHub App.
host
Package host reads the resource usage of the Linux machine shed runs on from procfs, sysfs, and statfs.
 Package host reads the resource usage of the Linux machine shed runs on from procfs, sysfs, and statfs.
logtail
Package logtail keeps the most recent lines of a log in memory and streams new ones to followers.
 Package logtail keeps the most recent lines of a log in memory and streams new ones to followers.
mcp
Package mcp serves shed's Model Context Protocol server, which lets coding agents inspect projects, services, deployments, logs, metrics, variable names, and backups.
 Package mcp serves shed's Model Context Protocol server, which lets coding agents inspect projects, services, deployments, logs, metrics, variable names, and backups.
metrics
Package metrics records the resource usage of service containers and of the host, and serves it as time series.
 Package metrics records the resource usage of service containers and of the host, and serves it as time series.
onepassword
Package onepassword keeps variables in 1Password vault items with a service account token, through the official 1Password Go SDK.
 Package onepassword keeps variables in 1Password vault items with a service account token, through the official 1Password Go SDK.
proxy
Package proxy runs an embedded Caddy server that terminates TLS and routes requests by host name to upstream services.
 Package proxy runs an embedded Caddy server that terminates TLS and routes requests by host name to upstream services.
s3
Package s3 is a small client for S3-compatible object storage.
 Package s3 is a small client for S3-compatible object storage.
store
Package store persists shed's state in SQLite.
 Package store persists shed's state in SQLite.
update
Package update keeps shed current.
 Package update keeps shed current.
variables
Package variables keeps the variables of services where they live: in shed.db, or, while 1Password is connected, in one item per service in a vault of the operator's.
 Package variables keeps the variables of services where they live: in shed.db, or, while 1Password is connected, in one item per service in a vault of the operator's.
vars
Package vars resolves Railway-style variable references.
 Package vars resolves Railway-style variable references.
Package web embeds the built dashboard.
 Package web embeds the built dashboard.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.