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:
guidal projects create --name demo
guidal projects switch demo2. Create the database
guidal db create --name demo-db --type postgresqlProvisioning takes a minute or two. Check progress:
guidal db listOnce it reports as running, link it to the project so services can read its connection details:
guidal db link demo-dbLinking injects a connection string into your services as an environment variable rather than making you copy credentials by hand. To see the credentials directly:
guidal db credentials demo-dbTreat 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
From your application's directory, build it on Guidal — no local Docker needed:
guidal deploy .When the build finishes it prints the image reference. Create the service from it:
guidal services create --name api \
--image <image reference> \
--port 8080Later deploys go straight to the service:
guidal deploy . --service apiSecret files such as .env are refused rather than uploaded — see Deploy from source for what is uploaded and how to exclude files. If you already have an image, create the service from it directly with --image; for a private image, see Container registry.
4. Configure it
Set the non-secret configuration as environment variables:
guidal env set LOG_LEVEL=info --service api
guidal env set FEATURE_SIGNUP=true --service apiAnything sensitive belongs in secrets instead:
guidal secrets set STRIPE_API_KEY --service apiBoth take effect on the next deploy. List what is currently set:
guidal env list --service api5. Add a domain
Plan requirement
Custom domains are available on Pro and Team. On Starter your service is reachable at its Guidal-assigned URL.
guidal domains add app.example.com --service apiThe command prints a DNS record to create at your provider. Once you have added it:
guidal domains verify app.example.comGuidal 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:
guidal services deploy api --image ghcr.io/your-org/your-app:v2If something is wrong, roll back:
guidal deployments list --service api
guidal deployments rollback --service apiWhere to go next
- Background workers for queue consumers
- Cron jobs for scheduled work
- Logs and Metrics
- Troubleshooting when a deploy misbehaves