Getting started

This guide takes a fresh DeployCrate team to a running application. It follows the product flow in the app: first you create a server and add the cloud credential from the New Server screen, then you choose the server type, provision and configure the server, create an application, configure staging and production, point DNS at the server, and deploy.

By the end, you should have:

• one provider credential stored in DeployCrate
• one managed server created in your cloud account
• one application connected to GitHub Releases Docker Hub GHCR a public image or a direct URL
• staging and production environments configured
• a domain record pointing to the server IP
• and a first manual deployment path you can verify before adding automation

What you need

• A DeployCrate account with a team workspace
• A cloud provider account with Hetzner or DigitalOcean
• Permission to create a provider API key or token
• A deployable application source
  • GitHub Releases for binary artifacts
  • Docker Hub or GHCR for container images
  • a public image
  • or a direct binary URL
• A domain or subdomain you control

1. Create a provider API key

Start in the cloud provider account where the server should live. Create an API key or token that allows DeployCrate to create servers and SSH keys. DeployCrate uses this token during provisioning; the server itself remains in your cloud account.

For Hetzner, create a Cloud API token for the project that should contain the server. For DigitalOcean, create a personal access token with permissions to create droplets and SSH keys. If the provider lets you scope the token to a project, team, or resource group, scope it as narrowly as practical.

Keep the token open while you move to DeployCrate. Most providers show the full secret only once, and DeployCrate cannot retrieve it from the provider later.

2. Start a new server

In DeployCrate, open Servers, click New Server, and start the server record. This is where you add the cloud credential; you do not need to visit the Provider Credentials page first.

Give the server a clear name, such as api-production-01, and leave the SSH port at 22 unless you know you need a different port. The server type selector currently defaults to Application; telemetry, database, and AI server types are planned but not part of the first setup path.

3. Create a provider credential

In the Credential field, click Add New. The dialog asks for a name, token, and provider. Give the credential a name that describes where it deploys, such as Production DigitalOcean or Hetzner EU project. Paste the API key from the provider, choose Hetzner or DigitalOcean, and save it.

DeployCrate adds the credential to the server form and selects it for you. Provider credentials are for infrastructure. DeployCrate decrypts them when it needs to talk to the provider API, for example when creating SSH keys, creating the VM, reading server status, or storing the external server ID. These credentials are not application secrets and are not injected into your app.

4. Select the server type

After the credential is selected, choose the server type. For the first setup, use Application. Click Configure Server to create the server record and move to the provisioning screen.

The provisioning screen shows the server details from the previous step and asks for the provider region or location and server size. The first server can be small; choose enough CPU and memory for the app plus some headroom for the operator, Docker, Caddy, logs, and future deployments.

5. Provision and configure your first server

Choose the provider region or location and server size, then click Provision Server. DeployCrate stores those provider-specific choices on the server record and queues the provisioning job.

Provisioning has two phases:

1. DeployCrate creates provider SSH keys for the admin and emergency users then creates the cloud VM and waits for the provider to report the server as ready
2. DeployCrate connects to the new server over root SSH then runs the bootstrap script and verifies that the operator health endpoint responds

Wait for the setup status page to finish before using the server as an application target. If provisioning fails, the setup events are the first place to look because they show whether the failure happened in provider provisioning, DNS, SSH bootstrap, or operator validation.

6. Create an application

Open the application wizard. Step 1 is application definition and source configuration.

Enter the application name and choose a default deployment strategy. The wizard currently offers:

Then choose the packaging type:

When the application is created, DeployCrate automatically creates staging and production environments using the default deployment strategy you chose.

7. Connect GitHub or Docker

Private sources need credentials before DeployCrate can resolve artifacts.

For GitHub Releases, click Add New in the GitHub Releases source configuration and connect GitHub. After GitHub is connected, choose the repository that publishes the release assets.

For Docker Hub or GHCR, click Add New in the Docker source configuration and store a username plus personal access token. Then enter the source reference, such as org/image for Docker Hub or ghcr.io/org/image for GHCR. Public images do not require credentials, but they still need a source reference such as nginx or caddy.

For the first deploy, prefer a source and release you can verify manually. Automated deployment endpoints are easier to debug after one manual deployment has already worked.

8. Configure environments

Step 2 of the wizard configures staging and production. Use the tabs to configure each environment separately.

For each environment, set:

• the domain that should serve the environment
• the deployment strategy
• port configuration
• rollout configuration
• server targets
• and environment secrets

Choose the server you just provisioned as the server target. A deployment cannot run for an environment until at least one server target is selected.

Add application secrets on the right side of the wizard. Use the single-secret dialog for one value or bulk add for multiple KEY=value lines. Secrets are scoped to the selected environment, so staging and production can use different database URLs, API keys, and feature flags.

9. Point DNS at the server

The domain field in the application wizard tells DeployCrate what hostname Caddy should route for that environment. It does not move DNS for you.

After the server is provisioned, copy the server IPv4 address from DeployCrate. In your DNS provider, create an A record for the environment hostname and point it at that IPv4 address.

Examples:

If your DNS provider asks for a TTL, use a short TTL while testing. Once traffic is stable, you can raise it. After DNS resolves to the server, Caddy can request TLS certificates and route traffic to the deployed application.

10. Understand the PORT variable

DeployCrate manages a PORT environment variable for deployed applications. Your application can listen on a fixed port or read PORT from the environment, but the right choice depends on packaging and deployment strategy.

For immediate deployments, a fixed application port can be enough because one instance is replaced directly.

For blue/green binary deployments, your application must read PORT from the environment. The wizard asks for blue and green application ports, and DeployCrate injects the right value into each instance. If the binary always binds to one hardcoded port, the second slot cannot start beside the first slot.

For Docker deployments, the application still needs to listen on the container port you configure in the wizard. DeployCrate maps managed host ports to the application port so traffic can be switched safely.

Use this pattern in your app whenever possible:

1	port := os.Getenv("PORT")
2	if port == "" {
3		port = "8080"
4	}

The fallback is useful for local development. In DeployCrate, expect PORT to be present.

11. Review and finalize

Step 3 shows the application, environments, domains, ports, rollout strategy, server targets, and secrets. Check this page before finalizing.

Pay special attention to:

• both staging and production have the expected domain
• each environment has at least one server target
• port values match what the application actually listens on
• blue/green binary apps read PORT
• secrets exist in the correct environment
• and DNS points the environment domain to the server IP

12. Deploy manually first

Create a release and deploy it to staging before wiring up automation. A manual deploy proves that source credentials, server access, environment secrets, port handling, and domain routing are all correct.

If staging works, deploy the same source version to production. If it fails, isolate the layer:

• source errors usually mean the GitHub Docker Hub or GHCR credential cannot resolve the artifact
• target errors usually mean the environment has no server target or the operator is unreachable
• startup errors usually mean missing secrets wrong command behavior or the app listening on the wrong port
• routing errors usually mean DNS does not point to the server IP or the domain entered in the wizard does not match the hostname you are opening

After the first deploy

Open the configured domain and confirm the application responds. Check the release status in DeployCrate, then inspect the application logs if the process starts but does not serve traffic.

Once the manual path works, connect automated release triggers or deployment endpoints. Keeping automation until the end makes failures easier to isolate: first infrastructure, then source access, then environment configuration, then release automation.