Containers

Gigadrive Network can run container images. A Dockerfile in your repository can be a Function like any other, and an image can run as a sidecar next to your Functions, such as a Redis that your code reaches at redis:6379.

Running a Dockerfile as a Function

Set runtime: docker on a functions entry whose path is a Dockerfile. The build uses the Dockerfile's directory as the build context, and routes reach the Function by the Dockerfile's path, like any other Function file:

version: 4

functions:
  Dockerfile:
    runtime: docker
    port: 3000
  api/index.js:
    runtime: node-22

routes:
  - source: ^/api(/.*)?$
    destination: api/index.js
  - source: /*
    destination: Dockerfile

A Dockerfile Function takes memory, max_duration, streaming, schedule, and port. memory defaults to 512 MB rather than the 128 MB other Functions get. symlinks and includeFiles do not apply, and the build fails if you set them. port is only accepted with runtime: docker.

A pattern that matches several Dockerfiles, such as services/*/Dockerfile, makes one Function from each. Every Dockerfile Function also gets a container name, taken from its directory: services/api/Dockerfile is api, and a Dockerfile at the project root is app. Two Dockerfiles that would get the same name fail the build, and so does a name that a containers entry already uses.

To run an image from a registry, or to set a build target, build arguments, an entrypoint, or environment variables for the image, declare it under containers instead.

Declaring containers

The containers block declares images by name. The following config file runs a Dockerfile in the repository as the Function that serves every path, with a Redis sidecar next to it:

version: 4

containers:
  web:
    build: .
    port: 3000
    env:
      REDIS_URL: redis://redis:6379
  redis:
    image: redis:7-alpine
    sidecar: true
    port: 6379

routes:
  - source: /*
    destination: container:web

Each key under containers is the container's name. A name starts with a lowercase letter and continues with up to 62 lowercase letters, digits, hyphens, or underscores, because it is also the hostname your code reaches a sidecar by. localhost is reserved. A config file declares at most 16 containers.

Every container needs exactly one image source:

• image pulls a public registry image, such as redis:7-alpine or ghcr.io/acme/api:1.4.
• build builds a Dockerfile from the repository during the deployment's build. A string is the build context directory. An object sets context, dockerfile, target, and args.

Images are built and run for linux/amd64.

Container Functions

A container without sidecar: true is a Function, and so is a Dockerfile Function. Routes reach it with the destination container:<name>, written without a leading slash like every other destination. When a deployment has one container Function, no routes, and no assets, every path routes to it.

Your server must accept HTTP on the container's port, on all interfaces. The port is port when you set it, otherwise the first port the image exposes, otherwise 8080. The process also receives that port as PORT.

A container Function takes memory, max_duration, streaming, and schedule with the same meaning as for any other Function. memory defaults to 512 MB.

Sidecars

A container with sidecar: true runs next to every Function in the deployment, including Functions built from your own source files. Your code reaches it at <name>:<port>, so the sidecar named redis in the preceding example answers at redis:6379.

• A deployment declares at most 4 sidecars.
• memory defaults to 256 MB. Each sidecar's memory is added to the memory of every Function it runs next to.
• Each sidecar needs its own port, and that port must differ from the ports your Function uses. Managed Functions use port 8080, and PHP Functions also use 9000.
• The first request to a cold Function waits until every sidecar accepts connections.

Every copy of your Function starts its own sidecars. Data a sidecar holds is not shared between copies, and it is gone when the copy stops. Use a sidecar for a cache or a local helper process, not for data you need to keep.

A sidecar that exits is started again. When it exits more than 10 times in a row without staying up for 30 seconds, it is not started again, and Gigadrive Network replaces the copy of your Function it runs in. That copy stops receiving requests within about 10 seconds, and the next request starts a new copy with fresh sidecars. The sidecar's output, and a line for each exit and restart, stays in your runtime logs, labeled with the sidecar's name.

Container settings

The following table lists every key a container accepts:

An image built to run as root runs as an unprivileged user instead. Files in the image stay readable and writable by that user, and the process can still listen on a port below 1024. A process that needs other root privileges fails to start. Each sidecar runs as a user of its own, so a sidecar cannot read the environment variables of the Function it runs next to.

Environment variables

A container Function receives the image ENV, then env, then your project's environment variables, with later values winning. A sidecar receives only the image ENV and its own env. It never receives your project's environment variables, so put no secrets in a sidecar's env, since that value is part of the config file.

Compose files

Set compose to the path of a Compose file to import its services as containers:

version: 4

compose: docker-compose.yml

A project with no config file and no framework that Gigadrive Network recognizes is detected from compose.yaml, compose.yml, docker-compose.yaml, or docker-compose.yml at its root, when that file declares an app as described in the following paragraph. Failing that, a root Dockerfile becomes a container Function named app. A Compose file that only runs images, such as a database for local development, never changes how a project deploys.

One service becomes the container Function and every other service becomes a sidecar under its service name. The Function is the service marked x-gigadrive: { public: true }. Without that mark, it is the one service that builds from source. When no service or several services build from source, the build fails until you mark one. The following Compose file serves the web service and runs cache as a sidecar:

services:
  web:
    build: .
    ports:
      - '3000:3000'
    environment:
      REDIS_URL: redis://cache:6379
  cache:
    image: redis:7-alpine
  seed:
    image: alpine
    x-gigadrive:
      skip: true

The import reads image, build, ports, expose, entrypoint, command, environment, env_file, working_dir, user, and a memory limit from mem_limit or deploy.resources.limits.memory. It resolves ${VARIABLE} references, including defaults, alternatives and required variables, from a .env file beside the Compose file. The .env file must be part of the deployed source: a file your .gitignore excludes is not uploaded, and its variables resolve to empty values. dockerfile_inline is not supported, and extends and override files are not merged. Services under a profile, and services marked x-gigadrive: { skip: true }, are left out. Volumes are not supported: the build prints a warning for a service that declares them, and anything written there is lost when the Function stops. An entry in containers with the same name as a Compose service replaces that service.

Related pages

• Routes
• Memory and CPU
• Configuration reference