Files
dokku/docs/getting-started/install/docker.md
T
Dokku Bot 4fc19fe1bc Release 0.38.28
# History

## 0.38.28

Install/update via the bootstrap script:

```shell
wget -NP . https://dokku.com/install/v0.38.28/bootstrap.sh
sudo DOKKU_TAG=v0.38.28 bash bootstrap.sh
```

### Bug Fixes

- #9033: @mvysny Discard the build record git:sync starts when nothing is built
- #9035: @vulragrag-star Fix builds:output exiting 0 for unknown build ids
- #9010: @visheshgubrani Reject scheduler mismatch at mount time
- #8975: @BetterAndBetterII Treat is_app_listening as a boolean, not a non-empty string
- #8972: @josegonzalez Validate k3s profile names against derived release name
- #8937: @josegonzalez Retire cron containers past their active deadline

### New Features

- #9047: @josegonzalez Release dokku on resolute
- #8791: @akhil-naidu Add Ubuntu 26.04 LTS to bootstrap supported versions
- #9003: @josegonzalez Distinct git:auth-status exit codes for netrc state
- #9001: @josegonzalez Add --clear and --replace flags to ps:scale
- #8996: @josegonzalez Add fingerprint and serial to certs:report

### Documentation

- #9036: @meteozond Add dokku-generic to community plugins

### Tests

- #9046: @dependabot[bot] chore(deps): bump ruby from 4.0.6 to 4.0.7 in /tests/apps/dockerfile-entrypoint
- #9045: @dependabot[bot] chore(deps): bump sass from 1.104.0 to 1.104.1 in /tests/apps/multi
- #9032: @dependabot[bot] chore(deps): bump djangorestframework from 3.18.0 to 3.18.1 in /tests/apps/dockerfile-release
- #9038: @dependabot[bot] chore(deps): bump monolog/monolog from 3.11.0 to 3.12.0 in /tests/apps/php
- #9040: @dependabot[bot] chore(deps): bump psycopg2-binary from 2.9.12 to 2.9.13 in /tests/apps/dockerfile-release
- #9014: @dependabot[bot] chore(deps-dev): bump heroku/heroku-buildpack-php from 294 to 295 in /tests/apps/php
- #9016: @dependabot[bot] chore(deps): bump slim/slim from 4.15.2 to 4.15.3 in /tests/apps/php
- #9019: @dependabot[bot] chore(deps): bump sass from 1.103.1 to 1.104.0 in /tests/apps/multi
- #9015: @dependabot[bot] chore(deps): bump monolog/monolog from 3.10.0 to 3.11.0 in /tests/apps/php
- #9004: @dependabot[bot] chore(deps): bump qs from 6.15.2 to 6.16.0 in /tests/apps/checks-root
- #9005: @dependabot[bot] chore(deps): bump golang from 1.27.0 to 1.27.1 in /tests/apps/gogrpc
- #9006: @dependabot[bot] chore(deps): bump golang from 1.27.0 to 1.27.1 in /tests/apps/zombies-dockerfile-no-tini
- #9007: @dependabot[bot] chore(deps): bump golang from 1.27.0 to 1.27.1 in /tests/apps/zombies-dockerfile-tini
- #9008: @dependabot[bot] chore(deps): bump golang from 1.27.0 to 1.27.1 in /tests/apps/go-fail-predeploy
- #9009: @dependabot[bot] chore(deps): bump golang from 1.27.0 to 1.27.1 in /tests/apps/go-fail-postdeploy
- #8998: @dependabot[bot] chore(deps): bump python from 3.15.0rc1-bookworm to 3.15.0rc2-bookworm in /tests/apps/dockerfile-release
- #8976: @dependabot[bot] chore(deps): bump google.golang.org/grpc from 1.83.1 to 1.83.2 in /tests/apps/gogrpc
- #8970: @dependabot[bot] chore(deps): bump gunicorn from 26.1.0 to 26.2.0 in /tests/apps/dockerfile-release
- #8969: @dependabot[bot] chore(deps): bump gunicorn from 26.1.0 to 26.2.0 in /tests/apps/python-flask
- #8968: @dependabot[bot] chore(deps): bump gunicorn from 26.1.0 to 26.2.0 in /tests/apps/multi
- #8965: @dependabot[bot] chore(deps): bump sass from 1.102.0 to 1.103.1 in /tests/apps/multi
- #8962: @dependabot[bot] chore(deps): bump golang from 1.26.6 to 1.27.0 in /tests/apps/go-fail-predeploy
- #8961: @dependabot[bot] chore(deps): bump golang from 1.26.6 to 1.27.0 in /tests/apps/go-fail-postdeploy
- #8960: @dependabot[bot] chore(deps): bump golang from 1.26.6 to 1.27.0 in /tests/apps/gogrpc
- #8959: @dependabot[bot] chore(deps): bump golang from 1.26.6 to 1.27.0 in /tests/apps/zombies-dockerfile-tini
- #8958: @dependabot[bot] chore(deps): bump golang from 1.26.6 to 1.27.0 in /tests/apps/zombies-dockerfile-no-tini
- #8957: @dependabot[bot] chore(deps): bump google.golang.org/grpc from 1.83.0 to 1.83.1 in /tests/apps/gogrpc
- #8954: @dependabot[bot] chore(deps): bump gunicorn from 26.0.0 to 26.1.0 in /tests/apps/dockerfile-release
- #8952: @dependabot[bot] chore(deps): bump gunicorn from 26.0.0 to 26.1.0 in /tests/apps/multi
- #8951: @dependabot[bot] chore(deps): bump gunicorn from 26.0.0 to 26.1.0 in /tests/apps/python-flask
- #8943: @dependabot[bot] chore(deps): bump golang from 1.26.5 to 1.26.6 in /tests/apps/zombies-dockerfile-no-tini
- #8944: @dependabot[bot] chore(deps): bump golang from 1.26.5 to 1.26.6 in /tests/apps/go-fail-postdeploy
- #8942: @dependabot[bot] chore(deps): bump golang from 1.26.5 to 1.26.6 in /tests/apps/go-fail-predeploy
- #8941: @dependabot[bot] chore(deps): bump golang from 1.26.5 to 1.26.6 in /tests/apps/gogrpc
- #8940: @dependabot[bot] chore(deps): bump golang from 1.26.5 to 1.26.6 in /tests/apps/zombies-dockerfile-tini
- #8947: @dependabot[bot] chore(deps): bump sqlparse from 0.5.5 to 0.6.0 in /tests/apps/dockerfile-release
- #8939: @dependabot[bot] chore(deps): bump google.golang.org/protobuf from 1.36.11 to 1.36.12 in /tests/apps/gogrpc

### Dependencies

- #9027: @dependabot[bot] chore(deps): bump mvdan.cc/sh/v3 from 3.14.0 to 3.14.1 in /plugins/docker-options
- #9039: @dependabot[bot] chore(deps): bump golang.org/x/crypto from 0.56.0 to 0.57.0 in /plugins/common
- #9041: @dependabot[bot] chore(deps): bump helm.sh/helm/v3 from 3.21.4 to 3.22.0 in /plugins/scheduler-k3s
- #9042: @dependabot[bot] chore(deps): bump github.com/cert-manager/cert-manager from 1.21.1 to 1.21.2 in /plugins/scheduler-k3s
- #9028: @dependabot[bot] chore(deps): bump mvdan.cc/sh/v3 from 3.14.0 to 3.14.1 in /plugins/cron
- #9023: @dependabot[bot] chore(deps): bump golang.org/x/sync from 0.22.0 to 0.23.0 in /plugins/common
- #9017: @dependabot[bot] chore(deps): bump golang.org/x/crypto from 0.55.0 to 0.56.0 in /plugins/common
- #9029: @dependabot[bot] chore(deps): bump mvdan.cc/sh/v3 from 3.14.0 to 3.14.1 in /plugins/scheduler-k3s
- #9026: @dokku-bot chore: bump herokuish to 0.11.17
- #9024: @dependabot[bot] chore(deps): bump github.com/go-openapi/jsonpointer from 1.0.0 to 1.0.1 in /plugins/scheduler-k3s
- #9025: @dependabot[bot] chore(deps): bump golang.org/x/sync from 0.22.0 to 0.23.0 in /plugins/scheduler-k3s
- #8978: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.42.1 to 1.43.0 in /plugins/common
- #8987: @dependabot[bot] chore(deps): bump mvdan.cc/sh/v3 from 3.13.1 to 3.14.0 in /plugins/cron
- #9018: @dependabot[bot] chore(deps): bump traefik from v3.7.12 to v3.7.13 in /plugins/traefik-vhosts
- #9020: @dependabot[bot] chore(deps): bump github.com/traefik/traefik/v2 from 2.11.56 to 2.11.57 in /plugins/scheduler-k3s
- #9021: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.42.1 to 1.43.0 in /plugins/scheduler-k3s
- #8988: @dependabot[bot] chore(deps): bump mvdan.cc/sh/v3 from 3.13.1 to 3.14.0 in /plugins/docker-options
- #9013: @dependabot[bot] chore(deps): bump github.com/fluxcd/pkg/kustomize from 1.39.0 to 1.40.0 in /plugins/scheduler-k3s
- #9012: @dependabot[bot] chore(deps): bump github.com/traefik/traefik/v2 from 2.11.55 to 2.11.56 in /plugins/scheduler-k3s
- #8999: @dependabot[bot] chore(deps): bump k8s.io/kubectl from 0.36.4 to 0.37.0 in /plugins/scheduler-k3s
- #8997: @dependabot[bot] chore(deps): bump python from 3.15.0rc1-alpine to 3.15.0rc2-alpine in /docs/_build
- #8977: @dependabot[bot] chore(deps): bump github.com/onsi/gomega from 1.42.1 to 1.43.0 in /plugins/buildpacks
- #8981: @dependabot[bot] chore(deps): bump timberio/vector from 0.57.0-debian to 0.58.0-debian in /plugins/logs
- #8982: @dependabot[bot] chore(deps): bump traefik from v3.7.11 to v3.7.12 in /plugins/traefik-vhosts
- #8980: @dependabot[bot] chore(deps): bump click from 8.4.2 to 8.5.0 in /docs/_build
- #8983: @dependabot[bot] chore(deps): bump github.com/gofrs/flock from 0.13.0 to 0.13.1 in /plugins/ps
- #8984: @dependabot[bot] chore(deps): bump k8s.io/kubernetes from 1.36.4 to 1.37.0 in /plugins/scheduler-k3s
- #8985: @dependabot[bot] chore(deps): bump github.com/gofrs/flock from 0.13.0 to 0.13.1 in /plugins/scheduler-k3s
- #8986: @dependabot[bot] chore(deps): bump importlib-metadata from 9.0.0 to 9.0.1 in /docs/_build
- #8967: @dependabot[bot] chore(deps): bump pymdown-extensions from 11.0.1 to 11.0.2 in /docs/_build
- #8966: @dependabot[bot] chore(deps): bump k8s.io/kubectl from 0.36.3 to 0.36.4 in /plugins/scheduler-k3s
- #8964: @dependabot[bot] chore(deps): bump k8s.io/kubernetes from 1.36.3 to 1.36.4 in /plugins/scheduler-k3s
- #8963: @dependabot[bot] chore(deps): bump traefik from v3.7.10 to v3.7.11 in /plugins/traefik-vhosts
- #8953: @dependabot[bot] chore(deps): bump github.com/traefik/traefik/v2 from 2.11.54 to 2.11.55 in /plugins/scheduler-k3s
- #8950: @dependabot[bot] chore(deps): bump pygments from 2.20.0 to 2.21.0 in /docs/_build
- #8945: @dependabot[bot] chore(deps): bump golang.org/x/crypto from 0.54.0 to 0.55.0 in /plugins/common
- #8949: @dokku-bot chore: bump herokuish to 0.11.16
- #8946: @dependabot[bot] chore(deps): bump helm.sh/helm/v3 from 3.21.3 to 3.21.4 in /plugins/scheduler-k3s
2026-09-17 21:43:15 +00:00

5.1 KiB

Docker Installation Notes

Pull the dokku/dokku image:

docker pull dokku/dokku:0.38.28

Next, run the image.

docker container run -d \
  --env DOKKU_HOSTNAME=dokku.me \
  --env DOKKU_HOST_ROOT=/var/lib/dokku/home/dokku \
  --env DOKKU_LIB_HOST_ROOT=/var/lib/dokku/var/lib/dokku \
  --name dokku \
  --publish 3022:22 \
  --publish 8080:80 \
  --publish 8443:443 \
  --volume /var/lib/dokku:/mnt/dokku \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  dokku/dokku:0.38.28

Alternatively, you can use docker-compose.yml:

services:
  dokku:
    image: dokku/dokku:0.38.28
    container_name: dokku
    network_mode: bridge
    ports:
      - "3022:22"
      - "8080:80"
      - "8443:443"
    volumes:
      - "/var/lib/dokku:/mnt/dokku"
      - "/var/run/docker.sock:/var/run/docker.sock"
    environment:
      DOKKU_HOSTNAME: dokku.me
      DOKKU_HOST_ROOT: /var/lib/dokku/home/dokku
      DOKKU_LIB_HOST_ROOT: /var/lib/dokku/var/lib/dokku
    restart: unless-stopped

Container readiness

The image ships with a Docker HEALTHCHECK that flips from starting to healthy once first-boot bootstrap is complete (skel restored, plugin-list plugins installed, core install triggers fired), nginx and sshd are accepting connections, and dokku ps:restore has finished. Until those conditions hold, the container is considered unhealthy and dependent services should not yet send traffic.

To check the current state from the host:

docker inspect --format='{{.State.Health.Status}}' dokku

Internally, the check is backed by a loopback-only HTTP endpoint:

docker exec dokku curl -fsS http://127.0.0.1:18080/_dokku/health

The endpoint binds to 127.0.0.1:18080 inside the container by design - it is not published to the host and does not interfere with user app vhosts on ports 80/443.

Compose dependents can gate on the healthcheck via depends_on with condition: service_healthy:

services:
  dokku:
    image: dokku/dokku:0.38.28
    # ...
  bootstrap:
    image: alpine:3.20
    command: ["echo", "dokku is ready"]
    depends_on:
      dokku:
        condition: service_healthy

Dokku is run in the following configuration:

  • The global hostname is set to dokku.me on boot.
  • The container name is dokku.
  • Container SSH port 22 is exposed on the host as 3022.
  • Container HTTP port 80 is exposed on the host as 8080.
  • Container HTTPS port 443 is exposed on the host as 8443.
  • Data within the container is stored on the host within the /var/lib/dokku directory.
  • Image build cache is set to the data dir + /home/dokku.
  • The docker socket is mounted into container.

Application repositories, plugin config, as well as plugin data are persisted to disk within the specified host directory for /var/lib/dokku.

Other docker container options can also be used when running Dokku, though the specific outcome will depend upon the specified options. For example, the Dokku container's nginx port can be bound to a specific host ip by specifying --publish $HOST_IP:8080:80, where $HOST_IP is the IP desired. Please see the docker container run documentation for further explanation for various docker arguments.

Plugin Installation

On Dokku start

To install custom plugins, create a plugin-list file in the host's /var/lib/dokku directory. The plugins listed herein will be automatically installed by Dokku on container boot. This file should be the following format:

plugin_name: repository_url

An example for installing the postgres and redis plugins follows:

postgres: https://github.com/dokku/dokku-postgres.git
redis: https://github.com/dokku/dokku-redis.git

Prior to Dokku start

The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any plugin:install command, though the install trigger must be skipped via the --skip-install-trigger. The version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.

FROM dokku/dokku:0.38.28
RUN dokku plugin:install https://github.com/dokku/dokku-postgres.git --skip-install-trigger
RUN dokku plugin:install https://github.com/dokku/dokku-redis.git --skip-install-trigger

SSH Key Management

To initialize ssh-keys within the container, use docker exec to enter the container:

docker exec -it dokku bash

Next, run the appropriate ssh-keys commands:

echo "$CONTENTS_OF_YOUR_PUBLIC_SSH_KEY_HERE" | dokku ssh-keys:add KEY_NAME

Please see the user management documentation for more information.

Pushing Applications

When exposing the Dokku container's SSH port (22) on 3022, something similar to the following will need to be setup within the user's ~/.ssh/config:

Host dokku.docker
  HostName 127.0.0.1
  Port 3022

In the above example, the hostname 127.0.0.1 is being aliased to dokku.docker, while the port is being overridden to 3022. All SSH commands - including git pushes - for the hostname dokku.docker will be transparently sent to 127.0.0.1:3022.