Services

A Service is a long-running container that serves HTTP: a REST API, a web app, a dashboard, an admin tool, or open-source and vendor software you didn't write. If it runs in a Docker container and answers HTTP requests, it can run as a Service.

Unlike a Function, a Service runs its own web server, and it keeps running between requests.

What your container needs

• A Dockerfile at the root of your ZIP. Coderunner builds your image from it.
• An HTTP server on port 8080, or on the port in the PORT environment variable.
• Bind to 0.0.0.0, not 127.0.0.1. Otherwise nothing outside the container can reach it.

my-service.zip
├── Dockerfile
├── package.json
└── src/

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 8080
ENV PORT=8080
CMD ["npm", "start"]

Deploy it

gf deploy --name my-api --workload-type service --runtime node --cpu 500m --memory 512Mi

How Coderunner knows it's healthy

There's no health check to configure. A deployment counts as ready once your container starts answering on its port. If it never does, the deployment is marked Failed and no traffic is sent to it. The most common cause is listening on 127.0.0.1 or on the wrong port.

Scaling

Set a minimum and maximum number of instances on the deployment, in the Client Portal's deploy dialog or with the API. Coderunner scales between them. For a site that should answer quickly, set the minimum to at least 1. See Resources and scaling.

Storage

A Service's file system is temporary: anything written to local disk is lost when it restarts or you redeploy. Keep data in a database and files in Files.

Domains

Every Service gets a Deployment URL, shown on its page in the Client Portal and printed by gf deploy. Anyone can reach this URL: Groundfloor doesn't sign anyone in before passing on a request. See Who can reach your Service.

To serve it on your own domain, attach the Service to an app and add the domain on its Domains tab or with gf domains add <domain> --app <app>: create the CNAME and TXT records it shows you, then verify. For a root domain such as example.com, use an ALIAS or ANAME record. A Service that isn't part of an app can't have a custom domain.

Running an off-the-shelf app

Software you didn't write, such as WordPress, Ghost or Metabase, runs as a Service like any other. Check these first:

• Port: many images listen on port 80. Change the app's configuration in your Dockerfile so it listens on 8080 (or PORT) on 0.0.0.0.
• Database: managed databases are PostgreSQL only. An app that needs MySQL, MariaDB or MongoDB, such as WordPress, needs a database you run elsewhere.
• Files and uploads: local disk is lost when the Service restarts, redeploys or scales to zero, and each instance has its own. Point the app's object-storage (S3) plugin at a storage service you run elsewhere. Files works for code you write, through the Files API; off-the-shelf apps can't use it directly.
• Sessions: with more than one instance, sessions kept in memory or on disk break as requests move between instances. Keep one instance, or store sessions in the app's database.
• Always on: set the minimum number of instances to at least 1, so the first visitor doesn't wait for it to start.
• Sign-in: the app's own login applies. Groundfloor sign-in can't be used for it today.
• Finish setup straight away: many apps, such as WordPress, run an installer on the first visit. Complete it as soon as the first deploy finishes: until you do, anyone who opens the URL can claim the site and become its admin.
• Admin pages are public too: pages such as /wp-admin can be reached by anyone. Use strong passwords and the app's own protections. See Who can reach your Service.

Next steps

• Who can reach your Service — decide who may use it.
• Example: run WordPress — a complete walkthrough with an off-the-shelf image.
• Configuration and secrets — settings and secrets for your container.
• Logs and troubleshooting — when a deployment fails.