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
podosfrom source. See Server requirements: the server needs BuildKit andcrun1.15 or newer. The install script provides both, once a release exists.
project = "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" }
project: 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:
- 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
giton your machine; ifgitis missing or fails, the deploy stops with a message. - Outside Git: every file.
- Then
.dockerignoreis 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:
- Sockets, named pipes, devices and Git submodules are skipped, with a warning on standard error.
- Symbolic links are sent as links and never followed, so a link cannot make
podos deployread a file outside the build directory. - A file name that starts with
.wh.is refused. Rename the file or list it in.dockerignore. - Names that are not valid UTF-8 and very long or deeply nested paths are refused, with the file named.
- A source larger than the limit (256 MiB by default) or with more than
200000 files and directories is refused. Exclude build outputs,
dependencies and logs in
.dockerignore.
.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)
building NAME from DIR: N files, SIZE (HOW)says what was packaged. HOW isfiles Git does not ignore,all files, or either one followed by, then .dockerignore.- Lines that start with
|are BuildKit's own log. built NAME: sha256:... (N layers, SIZE)ends the build. Then the normal release output follows.
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 project named like the directory. The service is private: it has no
port and no domain. podos deploy prints a notice that names the project.
Run podos init to write a manifest, then add port
and domains. The directory name must be a valid project name, or the
command asks you to use podos init --project 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 project 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
- Build arguments.
- Secrets in a build.
- Build targets (
--target). - Other platforms than the server's own.
- Private base images: no registry credentials reach the build. A
FROMimage must be public. - Builders other than a Dockerfile.
Things to know
- File times. The files in the built image do not have your files' modification times. The server sets a fresh time on the uploaded files for every build.
- Network. Build steps can reach the internet with the same rules as containers (the cloud metadata addresses are blocked). They cannot reach the environments' networks or the server's own services.
- Cache. BuildKit keeps a build cache on the server, capped at 10 GiB by default.
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
- Builds of one project run together, up to
--build-parallel. - Builds of different projects never run at the same time. They take turns in the order the requests arrived.
- A project may have at most 2 sources arriving at once, and at most
--build-parallelplus 2 builds in all.
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:
- BuildKit (
buildkitdandbuildctl) in/usr/local/lib/podos/bin. crun1.15 or newer. Thecrunthat Ubuntu 24.04 ships is 1.14, which is too old.
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
- Images built on the server are never cleaned up yet.
- A failed first build leaves an empty project.
See Limits.