Skip to Content
ConfigurationServices & ProvisioningNative Dockerfile Support

Native Dockerfile Support

Nanokit’s “Zero-Config” philosophy means that for most applications, you don’t need to write a Dockerfile. Nanokit automatically generates a secure, optimized image based on your Runtime.

However, some applications require highly specific system dependencies, complex multi-stage builds, or specific base images. In these cases, you can provide a native Dockerfile.

When to use a Native Dockerfile

  • System Dependencies: Your app requires native libraries (e.g. libvips, ffmpeg, graphicsmagick) that aren’t in the default runtime.
  • Multi-Stage Builds: You need a complex build process where build-time dependencies should not be in the final runtime image.
  • Legacy Images: You are migrating an existing containerized app and want to keep using your proven Dockerfile.
  • Specialized Base Images: You need to run on a specific OS or architecture (e.g. alpine, ubuntu).

Implementation in nanokit.yml

You can enable native Dockerfile support using the build property in your service configuration.

If you place a file named Dockerfile in your service directory, you can simply set build: true. Nanokit will automatically detect it.

services:
  api:
    path: ./apps/api
    build: true        # Looks for ./apps/api/Dockerfile

2. Custom Path

If your Dockerfile has a different name or is located elsewhere, provide the path relative to the project root.

services:
  web:
    path: ./apps/web
    build: ./apps/web/Dockerfile.prod

3. Advanced Configuration

For full control over the build process, use the object syntax. This allows you to specify a custom build context and build arguments.

services:
  worker:
    path: ./services/worker
    build:
      context: .             # Build context (relative to project root)
      dockerfile: worker.Dockerfile
      args:
        VERSION: "1.2.3"
        API_KEY: ${MY_SECRET_KEY}

How it works

When a native Dockerfile is detected:

  1. Bypass Zero-Config: Nanokit stops generating the default Dockerfile.
  2. Local Build: The image is built locally using your docker CLI.
  3. Registry Sync: Nanokit tags the image and automatically pushes it to your provider’s registry (e.g. AWS ECR) before deployment.
  4. Consistency: The same image is used across all environments, ensuring “Build Once, Deploy Anywhere” stability.

[!TIP] Even when using a native Dockerfile, you can still use Nanokit’s env and secrets properties. These will be injected into the container at runtime, not build time, keeping your images clean and portable.

OverviewLifecycle & Hooks