Set up Stagely in your cloud account
Run stagely setup for DigitalOcean, AWS, Google Cloud, Azure, Hetzner Cloud or Vultr. Compare what it needs on each cloud, then follow your cloud's page.
stagely setup prepares one Stagely environment in a cloud account. One cloud account can hold several environments. Run setup on your computer, as a member with the admin or owner role. You can run it again at any time to repair or upgrade the environment. Each run leaves the environment with one agent and one gateway, both enrolled and connected.
Choose your cloud
Each cloud has its own page with the resources that setup creates, the credentials, the registry and the isolation rules.
| Cloud | Command | Credentials | Registry | Stagelets kept apart by |
|---|---|---|---|---|
| DigitalOcean | stagely setup digitalocean |
API token | DigitalOcean Container Registry, from setup | Cloud firewall |
| AWS | stagely setup aws |
Access key of an IAM user | Amazon ECR, with a repository creation template | Security groups |
| Google Cloud | stagely setup gcp |
Service account key | Artifact Registry repository, from setup | Firewall rules on network tags |
| Azure | stagely setup azure |
Service principal | Azure container registry, from setup | Network security group on the stagelet subnet |
| Hetzner Cloud | stagely setup hetzner |
API token, and your registry’s user and password | Your own registry | iptables rules on each machine |
| Vultr | stagely setup vultr |
API key | Vultr Container Registry, from setup | iptables rules on each machine |
What setup does
- Environment. It finds the environment by name in your Stagely account. If the environment does not exist, setup creates it.
- Keys. It creates an SSH key for itself and a host key for each host. The hosts get their host keys at boot, so setup never trusts a key that it did not create.
- Cloud resources. It applies a Terraform module with OpenTofu or Terraform. The module creates a network, the agent host, the gateway host and firewall rules for each host. It also creates rules that let stagelet machines and build workers accept traffic only from the agent and the gateway. On DigitalOcean, Google Cloud, Azure and Vultr, it creates a container registry. On AWS, it lets build workers create Amazon ECR repositories under a prefix. On Hetzner Cloud, you bring your own registry.
- Install. Over SSH, it installs
stagely-agentandstagely-gatewayas systemd services. Each service runs as its own system user and reads its credentials from a file that only root can read. - Enroll. It gives each daemon a one-time enrollment token. Then it waits until each daemon connects to Stagely. After that, each daemon signs in with its own key pair.
The agent host accepts only SSH from your -operator-cidr ranges. The gateway host accepts ports 80 and 443 from anywhere, and SSH from your ranges.
Sign in first
stagely loginA consent page opens in your browser. Choose the account. Click Allow. The CLI’s token works only at Stagely’s API and only in the account that you chose. It works for at most one hour. After that, sign in again.
Flags every cloud takes
| Flag | Default | Meaning |
|---|---|---|
-environment |
required | Environment name in Stagely, such as production |
-stagelet-domain |
required | Domain that holds the stagelet host names, such as stagelets.example.com |
-operator-cidr |
required | Address range that can reach the hosts over SSH. Repeat the flag for more ranges. Use only your operators’ own addresses. If a range includes the gateway host, the gateway can reach the agent host. |
-binaries |
required | Directory with stagely-agent and stagely-gateway for linux/amd64 |
-acme-email |
none | Contact email for the ACME account that gets the gateway’s certificates |
-golden-image |
none | A golden image for stagelet machines and build workers, instead of the cloud’s stock Ubuntu image |
-tofu |
tofu, else terraform |
The OpenTofu or Terraform binary |
-work-dir |
one for each environment | Work directory. The default is the environment’s name under ~/.stagely/cli/setup/. See Keep the work directory. |
-ssh-port |
22 |
Port that setup connects to over SSH. This flag does not change the firewalls: the Terraform module always opens port 22. |
Point DNS at the gateway
At the end, setup prints the gateway’s address. Point *.<stagelet domain> at it with an A record.
On DigitalOcean, setup can add the record itself. Pass -dns-domain with a domain in DigitalOcean DNS that is a parent of the stagelet domain, such as example.com for stagelets.example.com. If the -dns-domain value is not a parent of the stagelet domain, setup adds no record. It also prints no reminder to add one, so add the record yourself.
The gateway gets a certificate for each stagelet host name through ACME, from Let’s Encrypt by default. Every certificate goes into public Certificate Transparency logs, so stagelet host names become public. Opening a stagelet still needs a pass from Stagely.
Keep the work directory
Setup keeps the module, its state and the keys in the work directory. A later run needs the state to find the resources that setup created, and the keys to reach the hosts. The files hold the hosts’ private host keys, so only you can read them. To connect to a host yourself:
ssh -i ~/.stagely/cli/setup/production/operator_ed25519 \
root@<host address>