> For the complete documentation index, see [llms.txt](https://no0dles.gitbook.io/hammerkit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://no0dles.gitbook.io/hammerkit/service.md). # Service Service can help task to perform their work. For example a database for your application or an api to your integration test run. Services can be defined to run in a container or forwarded from a kubernetes cluster. Each need of a task will be available in the container network by the name of the service. Local tasks can also use needs, but hammerkit will not provide a dns resolution. Instead, the connection details of each needed service are passed to the task as environment variables (see [environment hints](#environment-hints-for-local-tasks)). ## Container Similar to [container tasks](/hammerkit/task/container.md) need container services an image to run. Tasks can declare the need for services and before the task gets executed, hammerkit will ensure the service is running. [Healthchecks](/hammerkit/service/container.md#healthcheck) can be used, to ensure that the service is running and ready to be used. ```yaml services: postgres: image: postgres envs: POSTGRES_USER: api POSTGRES_DB: api POSTGRES_PASSWORD: 123456 healthcheck: cmd: "pg_isready -U postgres" ports: - 5432 tasks: api: image: node:alpine needs: [postgres] cmds: - node index.js ``` ## Kubernetes [Kubernetes services](/hammerkit/service/kubernetes.md) allow to use resources from local and remote kubernetes clusters. This allows easy integration with development or staging environments resources and can be used to debug/troubleshoot your application with data from other environments. ```yaml services: postgres-staging: context: staging ports: - 5432:5432 selector: type: deployment name: postgres tasks: api-staging: image: node:alpine needs: [postgres-staging] cmds: - node index.js ``` ## Connecting from a container task A container task shares a network with its needed services and reaches each one by its **service name** as the hostname, on the service's **container port**. You don't publish a port for this — `ports` are only needed to reach a service from your host. For the `postgres` service above (exposing `5432`), a container task connects with a URL like `postgres://api@postgres:5432/api` — `postgres` is the service name and `5432` the container port. Keep that string in a shared top-level `envs` block so the service and the task agree on it: {% code title=".hammerkit.yaml" %} ```yaml envs: DATABASE_URL: postgres://api@postgres:5432/api services: postgres: image: postgres:16-alpine envs: POSTGRES_USER: api POSTGRES_DB: api POSTGRES_HOST_AUTH_METHOD: trust healthcheck: cmd: "pg_isready -U api" ports: - 5432 tasks: migrate: image: node:24-alpine needs: [postgres] envs: DATABASE_URL: $DATABASE_URL cmds: - node migrate.js ``` {% endcode %} ## Environment hints for local tasks A local task (a task without an `image`) is not part of that container network, so hammerkit instead injects the connection details as environment variables. For every needed service the following variables are available, where `NAME` is the uppercased service name: * `HAMMERKIT__HOST` - host the service is reachable on. * `HAMMERKIT__PORT` - the primary published port. * `HAMMERKIT__PORT_` - the published port for a specific container port. The suffix is always the numeric container port (ports cannot be named), so this is mainly useful for services that expose more than one port. For a service named `postgres` exposing port `5432` a local task receives `HAMMERKIT_POSTGRES_HOST`, `HAMMERKIT_POSTGRES_PORT` and `HAMMERKIT_POSTGRES_PORT_5432`. ## Service dependencies Like tasks, services can declare `deps` and `needs`. Use `deps` when a service requires a task to run first (for example building an image input), and `needs` when a service depends on another service. ```yaml services: api: image: node:alpine deps: [install] needs: [postgres] cmd: node index.js postgres: image: postgres:16-alpine ports: [5432] tasks: install: image: node:alpine cmds: - npm ci ``` ## Starting and stopping services Services start and stop automatically based on the needs of the tasks you run. They can also be controlled directly with the cli: * `hammerkit up` starts the services. * `hammerkit down` stops the services. This is useful to keep shared services such as a database running across multiple task runs. {% hint style="info" %} A service's container is recreated when it starts, so data written inside it is lost on the next start unless you attach a [volume](/hammerkit/service/container.md#volumes). Declare a volume to persist a database's data — or to seed/back it up with [store / restore](/hammerkit/cli/store-restore.md). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://no0dles.gitbook.io/hammerkit/service.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.