Stagely

Quickstart: set up Stagely for your team

View as Markdown

Set Stagely up once: sign up, subscribe, link GitHub, set up your cloud, add .stagely.yml, a project and config, then open a pull request to get a stagelet.

This page is for the person who sets Stagely up for the team. You create the account, so you are its owner. At the end, every new pull request in your repository gets a stagelet without any manual step.

Before you start

You need:

  • Repositories on GitHub, and the right to install a GitHub App on the user or organization that owns them.
  • An app that runs with Docker Compose, within the Compose rules.
  • An account on DigitalOcean, AWS, Google Cloud, Azure, Hetzner Cloud or Vultr, and credentials that can create resources in it. Set up your cloud lists what each cloud needs.
  • A domain for stagelet host names, such as stagelets.example.com, where you can add a DNS record.
  • The public address range of the computer that runs setup. Only addresses in this range can reach your hosts over SSH.
  • On that computer: the stagely CLI, OpenTofu or Terraform, and the stagely-agent and stagely-gateway binaries for linux/amd64 in one directory. Each release has an archive of all three for your computer and one for linux/amd64, with checksums.

1. Create the account

Open the Stagely console. Click Continue with GitHub. Give the account a name, such as your company’s name. Click Create account. You are now its owner.

2. Subscribe

Open Billing. Choose Monthly or Annual, then click Subscribe to a plan to open Stripe Checkout. The first subscription starts with a 14-day trial, and Checkout asks for no card. When you finish checkout, the console shows that the account can deploy. Without a subscription, Stagely refuses deploys and says why. Plans and billing compares the plans.

Open Projects. Click Link GitHub. Choose the user or organization that owns your repositories. Install the Stagely GitHub App on it. The console then shows the installation as linked.

The App asks for these repository permissions: read contents and metadata, write pull requests (to reply to deploy commands) and write commit statuses (to show each deploy on the pull request). It receives pull request and issue comment events.

4. Set up your cloud

On your computer, sign the CLI in to Stagely. Then run setup for your cloud. This example uses DigitalOcean.

export DIGITALOCEAN_TOKEN=<token>
stagely login
stagely setup digitalocean \
  -environment production \
  -region fra1 \
  -stagelet-domain stagelets.example.com \
  -registry example-stagely \
  -operator-cidr 203.0.113.7/32 \
  -binaries bin/linux-amd64 \
  -acme-email ops@example.com

stagely login opens a consent page in your browser. Click Allow. Setup then creates the network, the agent host, the gateway host, their firewalls and a container registry. After that, it installs the agent and the gateway, and enrolls them.

At the end, setup prints the gateway’s address. Point *.stagelets.example.com at it with an A record.

Check: in the console, open Environments, then your environment. Under Connection, the agent and the gateway show Connected.

Set up your cloud has the steps and flags for every cloud.

5. Add .stagely.yml to the repository

Commit a .stagely.yml to the root of your repository. It names your Compose files, the service people open, its health check and an optional migration:

version: 1
compose:
  - deploy/compose.yml
public:
  service: web
  port: 8080
health:
  path: /healthz
migration:
  command: bin/rails db:migrate

Stagely reads it from each pull request’s head commit. See .stagely.yml for every field.

6. Create the project

In Projects, click New project. Choose the repository and the environment. Click Create project.

The defaults suit most teams: new pull requests and pushes deploy, the comment command is /stagely, label deploys are off, and Stagely deletes a stagelet 72 hours after its last deploy. Deploys from pull requests explains each setting.

7. Add config

In the project’s Config, add the plain values that your app needs. For each secret, add a secret reference here. Then store the value on the agent host. Config values and secrets shows the commands.

8. Open a pull request

Push a branch. Open a pull request from it. In the console, open Stagelets. The pull request’s stagelet appears there with the state Deploying. Click the stagelet to open its page. The page shows the steps and logs live. When the page shows Running, click Open on that page.

On GitHub, the pull request shows a stagely/<account> commit status. Its Details link opens the stagelet’s page in the console.

Next