Guidal
Sign in

Deploy your first app

A complete walkthrough — a web service, a Postgres database, environment variables and a domain.

The Quickstart gets a container running. This page builds something closer to a real application: a web service backed by Postgres, configured through environment variables, reachable on your own domain.

What you will build

A web service that reads its database connection from the environment, with a managed Postgres instance attached, served over HTTPS.

1. Create a project

Projects isolate environments from one another. Create one for this app:

bash
guidal projects create demo
guidal projects switch demo

2. Create the database

bash
guidal db create demo-db --engine postgres

Provisioning takes a minute or two. Check progress:

bash
guidal db list

Once it reports as running, link it to the project so services can read its connection details:

bash
guidal db link demo-db

Linking injects a connection string into your services as an environment variable rather than making you copy credentials by hand. To see the credentials directly:

bash
guidal db credentials demo-db

Treat credentials as secrets

guidal db credentials prints a live password to your terminal. Avoid running it in shared terminals or CI logs — prefer linking the database, which passes the connection string to the service without printing it.

3. Deploy the service

bash
guidal services create api \
  --image ghcr.io/your-org/your-app:v1 \
  --port 8080

If your image is in a private registry, see Container registry for how to push to the registry Guidal provides.

4. Configure it

Set the non-secret configuration as environment variables:

bash
guidal env set LOG_LEVEL=info --service api
guidal env set FEATURE_SIGNUP=true --service api

Anything sensitive belongs in secrets instead:

bash
guidal secrets set STRIPE_API_KEY --service api

Both take effect on the next deploy. List what is currently set:

bash
guidal env list --service api

5. Add a domain

Plan requirement

Custom domains are available on Pro and Team. On Starter your service is reachable at its Guidal-assigned URL.

bash
guidal domains add app.example.com --service api

The command prints a DNS record to create at your provider. Once you have added it:

bash
guidal domains verify app.example.com

Guidal issues a TLS certificate automatically once verification passes. Check it with guidal domains ssl app.example.com.

6. Ship a change

Deploy a new image tag:

bash
guidal services deploy api --image ghcr.io/your-org/your-app:v2

If something is wrong, roll back:

bash
guidal deployments list --service api
guidal deployments rollback --service api

Where to go next