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
gitandrailpackonPATH- 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(andAAAA) record for the dashboard host inserver.url, pointing at the server. - For generated service domains, set
proxy.base_domain(for exampleapps.example.com) and add a wildcard record*.apps.example.compointing at the server. - Custom domains need their own record pointing at the server.
First run
- 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. - 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.
- Install the App on the accounts or repositories you want to deploy.
- 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. |
|
shedlab
command
Command shedlab runs throwaway shed instances in local VMs for development.
|
Command shedlab runs throwaway shed instances in local VMs for development. |
|
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. |
|
audit
Package audit keeps shed's audit log: one event per mutation, sign-in, denial, and security-relevant read, saying who acted, from where, on what, and whether it worked.
|
Package audit keeps shed's audit log: one event per mutation, sign-in, denial, and security-relevant read, saying who acted, from where, on what, and whether it worked. |
|
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, updates, and telemetry: the rules every interface to shed shares.
|
Package control holds shed's operations on projects, services, deployments, variables, domains, volumes, backups, metrics, updates, and telemetry: 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. |
|
grafana
Package grafana is everything shed knows about Grafana: the container's configuration, the provisioning files for data sources and default alert rules, a client for the HTTP API (folders, dashboards, annotations, alerts), and the dashboards shed creates, built in Go from templates.
|
Package grafana is everything shed knows about Grafana: the container's configuration, the provisioning files for data sources and default alert rules, a client for the HTTP API (folders, dashboards, annotations, alerts), and the dashboards shed creates, built in Go from templates. |
|
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, backups, and the audit log.
|
Package mcp serves shed's Model Context Protocol server, which lets coding agents inspect projects, services, deployments, logs, metrics, variable names, backups, and the audit log. |
|
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. |
|
netns
Package netns opens TCP listeners inside the network namespaces of other processes, such as a container's init process.
|
Package netns opens TCP listeners inside the network namespaces of other processes, such as a container's init process. |
|
observability
Package observability runs the telemetry stack: VictoriaMetrics, VictoriaLogs, VictoriaTraces, and Grafana, each a container on the host network listening on loopback.
|
Package observability runs the telemetry stack: VictoriaMetrics, VictoriaLogs, VictoriaTraces, and Grafana, each a container on the host network listening on loopback. |
|
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. |
|
otlp
Package otlp is shed's OTLP/HTTP receiver, the heart of its telemetry gateway.
|
Package otlp is shed's OTLP/HTTP receiver, the heart of its telemetry gateway. |
|
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. |
|
telemetry
Package telemetry builds shed's own OpenTelemetry tracer, meter, and logger providers.
|
Package telemetry builds shed's own OpenTelemetry tracer, meter, and logger providers. |
|
telemetry/telemetrytest
Package telemetrytest records what instrumented code sends to the OpenTelemetry globals, for tests.
|
Package telemetrytest records what instrumented code sends to the OpenTelemetry globals, for tests. |
|
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. |
|
victoria
Package victoria holds small HTTP clients for the three stores shed runs when telemetry is on: VictoriaMetrics, VictoriaLogs, and VictoriaTraces.
|
Package victoria holds small HTTP clients for the three stores shed runs when telemetry is on: VictoriaMetrics, VictoriaLogs, and VictoriaTraces. |
|
Package web embeds the built dashboard.
|
Package web embeds the built dashboard. |
Click to show internal directories.
Click to hide internal directories.