Web services — Guidal Docs

A web service is a container that listens on a port and serves HTTP traffic. Guidal gives it a URL, keeps it running, restarts it if it exits, and routes traffic across its replicas.

If your workload has no port and consumes a queue instead, you want a background worker.

Create one

bash

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

--port is the port inside the container. Guidal terminates TLS and forwards to it; your application does not need to handle certificates.

Deploy a new version

bash

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

The new version starts before the old one stops, so a healthy deploy does not drop traffic. If the new version never becomes healthy, the old one keeps serving.

Scale

bash

guidal services scale api --replicas 3

Replicas share incoming traffic. Your plan sets the ceiling:

Plan	Max replicas per service
Starter	3
Pro	10
Team	20

Scaling helps with concurrency, not with a slow dependency — three replicas all waiting on the same overloaded database are no faster than one.

Inspect

bash

guidal services list
guidal services get api
guidal logs query --service api
guidal metrics service api

Roll back

bash

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

Rollback redeploys a previous image. It does not revert environment variables or secrets — if a bad deploy also changed configuration, revert that separately.

Delete

bash

guidal services delete api

This stops the service and releases its URL. Attached databases and buckets belong to the project and are not deleted with the service.

Health and restarts

A container that exits is restarted automatically. A container that exits repeatedly and quickly is backed off — restarted with increasing delay rather than in a tight loop — so a crash on startup shows up as a service that never becomes ready rather than as a spinning restart.

The usual causes are a missing environment variable, a port mismatch between --port and what the application binds, or a dependency that is not reachable yet. guidal logs query --service api names the reason in almost every case.

Plan limits

Plan	Max web services
Starter	3
Pro	20
Team	25

Creating a service beyond the limit is refused with a clear error rather than silently queued.