# Deploy any app with a Dockerfile

Deploy any language or framework on Hangar by building the Dockerfile in your repository, with a domain, HTTPS and a deploy on every push.

If your app builds with `docker build`, it runs on Hangar. A Dockerfile is the way to deploy a language the automatic builder does not cover, or to control exactly what goes into the image.

## A Dockerfile that deploys well

Three things matter more than the rest:

1. **Listen on `0.0.0.0`** and on a known port.
2. **Read configuration from environment variables**, not from files baked into the image.
3. **Use a multi-stage build**, so the final image carries the app and not the compiler.

A Go service as an example:

```dockerfile
FROM golang:1.25 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=build /app /app
EXPOSE 8080
CMD ["/app"]
```

Add a `.dockerignore` that leaves out `.git`, dependency folders and local env files. It makes builds faster and keeps secrets out of the image.

## 1. Create the service

Create a project, add a service and pick your repository and branch. Choose a region.

## 2. Choose the Dockerfile builder

In the service's **Settings → Source**, select **Dockerfile** and set the path to the file, relative to the root directory. The default is `Dockerfile`.

For less common layouts, the advanced settings take a **build context** and a **target stage**. See [Builds](https://tryhangar.io/docs/builds).

## 3. Variables and build arguments

Runtime configuration goes in the **Variables** tab and reaches the container as environment variables.

Values a `RUN` step needs during the build are **build arguments**, declared in the Dockerfile with `ARG`:

```dockerfile
ARG APP_VERSION
RUN echo "building $APP_VERSION"
```

> [!CAUTION]
> Do not pass secrets as build arguments: they can remain in the image's history. Use build secrets for credentials a build step needs, such as a private registry token.

## 4. Deploy and add a domain

Deploy the service. In **Settings → Networking**, add a domain, set the container port to the port your app listens on (`8080` in the example) and turn HTTPS on.

## 5. Push to deploy

Every push to the connected branch rebuilds the image and deploys it. Layers that did not change are reused from the cache.

## Deploying a prebuilt image

If your CI already builds and pushes an image, skip the build: create a service with **Docker image** as its source and give it the image name, plus registry credentials if the image is private.

## Troubleshooting

- **The build cannot find a file**: the build context is not the directory you expect. Set it explicitly.
- **502 on the domain**: the container port does not match, or the app listens on `127.0.0.1`.
- **The container exits immediately**: read the runtime logs. The usual cause is a missing environment variable.

## Frequently asked questions

### Can Hangar deploy a Dockerfile from a subdirectory?

Yes. Set the Dockerfile path relative to the service's root directory, and set the build context if it differs from the root. This is how several services deploy from one monorepo.

### Can I deploy a prebuilt Docker image instead of building on Hangar?

Yes. A service can use a Docker image from a registry as its source. Hangar pulls the image and runs it, with no build step.

### Does Hangar support multi-stage Dockerfiles?

Yes. The last stage is built by default, and you can name a different target stage in the build settings.
