Podos A lightweight container platform Early development · not released

Guides

Build from source

Available

With a Dockerfile in the application directory, a service can be built on the server instead of pulled. podos deploy packages the directory, uploads it, the server builds it with BuildKit and the release uses the image that came back. No registry is needed.

There are no release binaries yet; build podos from source. See Server requirements: the server needs BuildKit and crun 1.15 or newer. The install script provides both, once a release exists.

TOML
namespace = "shop"

[service.web]
build = "."
port = 3000
domains = ["shop.example.com"]
health = "/healthz"
env = { DATABASE_URL = "postgres://app:${secret.DB_PASSWORD}@db:5432/shop" }

[service.db]
image = "postgres:17"
volumes = { data = "/var/lib/postgresql/data" }
YAML
namespace: shop

service:
  web:
    build: .
    port: 3000
    domains: [shop.example.com]
    health: /healthz
    env:
      DATABASE_URL: "postgres://app:${secret.DB_PASSWORD}@db:5432/shop"

  db:
    image: postgres:17
    volumes:
      data: /var/lib/postgresql/data

podos init writes build = "." when it finds a Dockerfile. A service has either build or image, not both; see build.

The Dockerfile

The file must be named Dockerfile and sit at the root of the build directory (the directory build names). It must be a regular file, not a link. build = "services/api" builds the directory services/api of the application directory; the build sees only that directory.

What is sent

podos deploy decides which files go to the server:

  1. Inside a Git work tree: every file Git does not ignore. That is the tracked files and new files that are not committed yet. This needs git on your machine; if git is missing or fails, the deploy stops with a message.
  2. Outside Git: every file.
  3. Then .dockerignore is applied.

The .git directory is never sent. Dockerfile and .dockerignore are always sent, even when .gitignore or .dockerignore lists them.

What is left out or refused:

.dockerignore

The file is in the build directory. One pattern per line:

Pattern Meaning
# text and blank lines Ignored.
* and ? Any run of characters, or any one character, except /.
[a-z], [^a-z] One character of a class, or not of it.
** Any number of directories, including none: **/test, docs/**.
\ The next character is literal.
!pattern Puts back what an earlier line left out.

Patterns are relative to the build directory. A leading and a trailing / mean nothing. The last line that matches a path decides. A line that is . or / is ignored. Dockerfile.dockerignore is not read by the CLI.

What you see

building web from .: 42 files, 1.3 MiB (files Git does not ignore)
  | #1 [internal] load build definition from Dockerfile
  | ...
built web: sha256:... (6 layers, 48.2 MiB)

Several services with the same build directory are built once.

Deploy without a manifest

A directory with a Dockerfile and no manifest deploys as service web in a namespace named like the directory. The service is private: it has no port and no domain. podos deploy prints a notice that names the namespace. Run podos init to write a manifest, then add port and domains. The directory name must be a valid namespace name, or the command asks you to use podos init --namespace NAME.

When a build fails

What happened What you see Exit code
A step of the Dockerfile failed BuildKit's error. No release is made and the previous release keeps serving. 1
The build took longer than the limit The build is cancelled with an error. 1
The source is too large or not valid The error names the limit or the file. 1
The server has no BuildKit or its crun is too old A message that says so. image still works. 1
The queue is full, the build waited too long for its turn, the namespace has too many builds, or the disk is nearly full An error that ends with "try again later". 3
Too many builds from one token (10 per minute) A rate-limit error. Refused requests count too. 3
You pressed Ctrl+C, or the connection closed interrupted; the build on the server is cancelled, or a message that the daemon closed the connection. 3

A failed build never starts a release. Fix the cause and run podos deploy again.

The syntax line and refused options

A first line # syntax=docker/dockerfile:1 works. The server downloads that frontend at build time. A frontend from any other repository is refused.

RUN --security=insecure and RUN --network=host are refused: build steps never get host network or extra privileges.

Not supported in this version

Things to know

Limits and daemon flags

These are set with flags of podos daemon:

Setting Default Flag
Time of one build 15 minutes --build-timeout
Memory of the builder, all builds together half of the server's memory, at least 512 MiB and at most 8 GiB --build-memory
Build cache 10 GiB --build-cache-max
Source accepted 256 MiB --build-context-max
Builds that run at once the number of CPUs, at most 4 --build-parallel, 1 to 8

Other limits: a build waits at most 10 minutes for its turn. One token may start 10 builds per minute, refused requests included. A build is cancelled when the free disk space of the data directory falls below the server's minimum (--min-free-disk).

Order of builds

The builder

BuildKit runs only while builds run. It starts with the first build and stops after 5 minutes without one. The daemon starts it; you do not run it.

Server requirements

A build needs two things on the server:

The install script puts both in place. Without them, a release with build is refused with a message that says what is missing; a release with image still works.

Known gaps

See Limits.