Deployment with Docker

Base image. swift:6.3-noble is the Docker Official Image of the Swift toolchain on Ubuntu 24.04 (noble). It was 5.27 GB on disk when pulled here (1.25 GB of compressed content), which is why it must not be the image you ship. The tag is a moving one: it follows Swift 6.3 patch releases, and on the day of the run it resolved to Swift 6.3.3. For reproducible builds, pin the digest (see Pinning base images). The toolchain’s Swift version must be at least the package’s swift-tools-version: the template package declares 6.3, so the template’s Swift 6.3 image is the minimum for the template’s own package, while a package declared with 6.0 (as Vapor itself is) also builds on older 6.x images.

OS updates and libjemalloc-dev. apt-get dist-upgrade pulls the latest security fixes of the base image. libjemalloc-dev provides the library and linker symlink for -ljemalloc in the build step. Combining update, upgrade and install in one RUN keeps the package index out of a stale layer.

Dependency caching. Docker caches a layer as long as the instruction and the files it copied are unchanged. The template copies only Package.* (that is Package.swift and Package.resolved) and runs swift package resolve before it copies the sources. Editing a Swift file therefore leaves the resolved-and-cloned dependency layer valid, and only the later steps run again. The $([ -f ./Package.resolved ] && echo "--force-resolved-versions" || true) fragment makes the build use exactly the versions in your committed Package.resolved and fail if they disagree with Package.swift, instead of silently resolving newer ones; without a Package.resolved it resolves freely. Commit Package.resolved for an application.

The build step. One long RUN does four things:

Source: vapor/template: Dockerfile

There is no libswiftCore.so and no libFoundation.so in that list, which is what --static-swift-stdlib buys. The same step then copies the executable and every *.resources bundle that SwiftPM produced (for example for a package that declares resources:) into /staging. The cache mount disappears when the RUN ends, so anything needed later must be copied out inside the same RUN, which is why the cp is chained with && to the build.

Staging. The next RUN instructions assemble everything the runtime needs in /staging:

Source: vapor/template: Dockerfile

If your application writes files (uploads, generated PDFs), put them in a volume mounted somewhere the vapor user owns, not in Public.

Base image. ubuntu:noble is the same distribution and release as the builder. That matters: the executable links against the glibc of the image that built it, and a glibc is only forward compatible. See The run base must not be older than the build base for what happens with an older distribution.

Runtime packages. The template installs libjemalloc2 (the runtime half of what the build linked), ca-certificates (needed for any outbound HTTPS or TLS to a managed database) and tzdata (time zones for DateFormatter and TimeZone). It runs dist-upgrade first, then removes the package lists to keep the layer small. The two commented-out packages matter when your application, or a dependency, imports FoundationNetworking (libcurl4, which URLSession on Linux uses, and AsyncHTTPClient does not need) or FoundationXML (libxml2). If a container exits at start with error while loading shared libraries: libcurl.so.4, this is the cause.

The vapor user. useradd --user-group --create-home --system --skel /dev/null --home-dir /app vapor creates a system user and group (uid and gid 999 here) whose home is /app, with no shell skeleton files. COPY --chown=vapor:vapor makes the files belong to it and USER vapor:vapor makes it the identity of the process and of every later instruction:

Source: vapor/template: Dockerfile

Running as a non-root user means a remote code execution bug in the service does not hand over root in the container, and it is a prerequisite for the Kubernetes runAsNonRoot policies and for read-only root file systems. Port 8080 is above 1024, so no privilege is needed to bind it.

Crash reporting. SWIFT_BACKTRACE=enable=yes,sanitize=yes,threads=all,images=all,interactive=no,swift-backtrace=./swift-backtrace-static configures Swift’s runtime crash handler: print a backtrace (enable=yes), redact paths to avoid leaking build machine details (sanitize=yes), include all threads and loaded images, never prompt (interactive=no), and run the helper from the relative path ./swift-backtrace-static, which resolves against the working directory /app. Without it a Swift server that traps on an Optional force-unwrap or an array index logs nothing useful. This was verified to be set in the image; a deliberate crash to read a backtrace was not run for this page.

Port, entrypoint and command. EXPOSE 8080 is documentation; it publishes nothing until you run with -p. The split between ENTRYPOINT and CMD is the useful part:

The hostname is the part people miss. The server’s default address is 127.0.0.1 (see Server Configuration), which inside a container is the container’s own loopback, unreachable through the published port. --hostname 0.0.0.0 binds all interfaces. Without it docker run -p 8080:8080 starts cleanly, logs Server started on http://127.0.0.1:8080, and every request from the host is reset.

Stopping. Because the executable is PID 1 in exec form, docker stop delivers SIGTERM to it and Vapor’s lifecycle shuts the HTTP server and connection pools down in an orderly way. In the run above, docker compose stop app returned in 0.2 s with exit code 0, the log shows Requesting HTTP server shutdown and HTTP server shutting down, and Docker’s default 10-second grace period before SIGKILL was never reached. The server’s own limit for in-flight requests is shutdownTimeout (default 10 seconds, see Production and Performance); if your requests run longer, raise both. With the shell form (CMD ./Bookshelf serve) a shell would be PID 1, and the signal would not reach Vapor, so the stop would always wait for the full grace period and then kill the process.

Source: Vapor docs: Docker Deploys

The first build took 7 minutes 9 seconds on this machine, almost all of it compiling Vapor, NIO, Fluent and PostgresNIO in release mode. After adding a comment to routes.swift, the second build took 12 seconds: the steps up to and including swift package resolve were CACHED, COPY . . reran, and the cache mount let swift build recompile only the changed file (Compiling Bookshelf Book.swift, Build of product 'Bookshelf' complete! (7.44s)). Changing Package.swift or Package.resolved invalidates the resolve layer and re-clones the dependencies, but the cache mount still holds the objects of unchanged packages. In CI, where there is no local cache, export and import the cache with --cache-to and --cache-from; see CI/CD with GitHub Actions. Running the test suite in CI is covered on the Testing page.

Cross-architecture builds. An image built on Apple Silicon is linux/arm64 and will not start on an amd64 server (exec format error). Build the architecture you deploy with docker buildx build --platform linux/amd64 (see BuildKit and Buildx); under emulation a Swift release build is many times slower, so prefer a native builder or CI runner for each architecture. This was not run for this page.

The template’s file has two lines:

Source: vapor/template: .dockerignore

They keep a macOS .build directory (which contains macOS binaries, and can be gigabytes) out of the build context, which would otherwise be sent to the daemon and copied by COPY . .. The template’s list is a minimum. COPY . . copies everything else into the build stage, including .git, .env and any .env.production file. Those files are discarded with the build stage, so they do not end up in the final image, but they do end up in the build cache and in the build context sent to a remote builder, and a later edit that adds a second COPY could ship them by accident. A safer file:

Source: Docker docs: Build context, .dockerignore files

Because the Dockerfile stages only /staging, no .env file can reach the run image unless you add a COPY for it. Vapor reads .env files from the working directory (see the dotenv section of Configuration and Environment); in a container, prefer real environment variables.

Schema changes are not part of serve. Running migrate is a separate step (see Migrations and Schema and Commands), and in a container you run it as a job from the same image that will serve, so the migration code and the model code cannot disagree:

Source: Vapor docs: Docker Deploys

--yes answers the confirmation prompt that migrate otherwise asks on a terminal, which a job cannot answer. docker compose run ignores replicas: 0 because you are naming the service explicitly. revert is the same job with --revert, which undoes only the last batch, so use it on purpose; run it to roll back a deployment that included a migration. Do not call app.autoMigrate() in configure for a service that runs as several replicas, since all of them would migrate at start-up at once; the one-off job has no such race.

depends_on: - db waits only until the db container has started, not until PostgreSQL accepts connections. On a cold start migrate or app can try to connect first and exit with a connection error. A healthcheck plus condition: service_healthy makes the order real. The next file keeps the template’s three services, with the changes a first deployment on a single host needs: secrets from a .env file that is not committed, info logs, a restart policy, a healthcheck on both containers, a read-only root file system with all Linux capabilities dropped, no published database port, and migrate behind a profile instead of replicas: 0.

Source: Docker docs: Control startup and shutdown order in Compose

The .env file next to it holds one line, with a placeholder you replace with a long random value:

Source: Docker docs: Compose variable interpolation

Run with docker compose -f docker-compose.prod.yml run --rm migrate and then up -d app; the result, after the database and the app had settled, was:

Points worth knowing about this file:

These numbers were measured for the image built above (Docker’s "disk usage" column; the compressed content is smaller):

The runtime base is a quarter of the image; the executable is half of it. The executable is large because it statically contains the Swift runtime, Foundation, NIO and the debug information of all of them. Two ways to reduce it, measured on the executable from this image:

The compiled executable asks for the C library symbols of the builder. Using an older distribution as the run image fails at start, not at build. The same executable copied into debian:bookworm-slim (glibc 2.36) produced:

while debian:trixie-slim (a newer glibc) ran it. The rule: the run image’s glibc must be the same as, or newer than, the build image’s. That is why the template pairs swift:6.3-noble with ubuntu:noble, and why you change both when you move to the next Ubuntu release. The same constraint applies to the swift-backtrace-static helper copied from the builder.

Other variants, not run for this page:

swift:6.3-noble and ubuntu:noble are tags, and a tag is a pointer that moves when the maintainers publish a patched image. That is wanted for security fixes (the template runs apt-get dist-upgrade on top for the same reason) and unwanted for reproducibility. The build log records the digests it resolved, and the FROM line accepts them:

Source: Dockerfile reference: FROM

(That is the digest swift:6.3-noble had on the day of the run; read the current one with docker buildx imagetools inspect swift:6.3-noble.) Pinned digests are updated deliberately, by a pull request that a tool such as Dependabot or Renovate opens, rather than at whatever hour the tag moves. Pin the final image you deploy by digest as well (image: registry.example.com/bookshelf@sha256:...). Consult Image Best Practices and Supply-Chain Security for scanning, SBOMs and signing, and Docker Security for the runtime side.