Zeabur Dockerfile Generation

Always use npx zeabur@latest to invoke Zeabur CLI. Never use zeabur directly or any other installation method. If npx is not available, install Node.js first.

When deploying source code to Zeabur, you must generate a Dockerfile. This skill covers how to analyze a project and produce a correct, deployable Dockerfile.

Prerequisites

Before generating a Dockerfile, read the key project files:

Language	Files to read
Node.js	`package.json`, lockfile (`package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`)
Python	`requirements.txt`, `Pipfile`, `pyproject.toml`
Go	`go.mod`
Rust	`Cargo.toml`
PHP	`composer.json`
Ruby	`Gemfile`
Java	`pom.xml`, `build.gradle`
.NET	`.csproj`, `.sln`
Elixir	`mix.exs`

Also check for:

Existing Dockerfile or docker-compose.yml
Build config (vite.config.js, webpack.config.js, next.config.js, etc.)
.env.example for required environment variables

What NOT to read — skip these to save tokens:

HTML files — static assets, never affect deployment logic
Lockfile contents — only check which lockfile exists (to determine package manager). Do NOT parse the contents.
Markdown files — documentation only, never influences Dockerfile decisions

Workflow

1. Analyze the Project

From the prerequisite files, determine:

Programming language and version
Framework (if any)
Package manager
Build command
Start command
Port the app listens on
Static site vs server-side app

2. Generate the Dockerfile

General Rules

No comments in the Dockerfile
No ENV or ARG instructions (unless required by the framework — see language-specific sections)
Add LABEL "language"="<lang>" — possible values: nodejs, python, go, static, ruby, java, php, rust, dotnet, elixir, swift, bun
Add LABEL "framework"="<framework>" only for actual web frameworks (see list below)
Always COPY . . before running any install/build commands
Set WORKDIR /src unless the user specifies otherwise
Add EXPOSE for the port the app listens on
Do not use multi-stage builds unless the build image differs from the runtime image (e.g., build with Node.js, serve with zeabur/caddy-static)

Framework vs Package — Only These Get a Framework Label

Frameworks (use LABEL "framework"="..."): vite, create-react-app, next.js, remix, nuxt.js, umi, nest.js, hexo, vitepress, astro, sli.dev, docusaurus, nitropack, hono, medusa, svelte, flask, django, fastapi, spring-boot, laravel, thinkphp, rails, aspnet, blazorwasm, elysia, baojs

Never label as framework (these are packages/libraries):

Python: gradio, pandas, numpy, requests, matplotlib, scikit-learn, tensorflow, pytorch, opencv, pillow, beautifulsoup4, selenium
Node.js: express, koa, hapi, fastify, socket.io, moment, lodash, axios
Other: bootstrap, jquery, chart.js, three.js, d3.js

If unsure whether something is a framework or package, do NOT add the framework label.

Static Sites — `zeabur/caddy-static`

For pure static websites (Vite, Astro static, Docusaurus, plain HTML), use zeabur/caddy-static:

FROM node:22-slim AS build
LABEL "language"="nodejs"
LABEL "framework"="vite"
WORKDIR /src
COPY . .
RUN npm install
RUN npm run build

FROM zeabur/caddy-static
COPY --from=build /src/dist /usr/share/caddy

Rules for zeabur/caddy-static:

Copy build output to /usr/share/caddy
Do NOT add CMD or ENTRYPOINT — the image handles it
It listens on port 8080
Only use for truly static sites. Do NOT use for SSR frameworks (Next.js, Nuxt.js, SvelteKit, etc.)
If building with Node.js then serving as static, set LABEL "language"="nodejs" (not "static")

Node.js

Default base image: node:22-slim
Determine package manager by lockfile presence:

Lockfile	Package manager	Install command
`package-lock.json`	npm	`npm install`
`yarn.lock`	yarn	`yarn install`
`pnpm-lock.yaml`	pnpm	`RUN npm install -g pnpm && pnpm install`

When using npm, use npm install. Do NOT use npm ci or flags like --only=production, --omit=dev, --frozen-lockfile.
For Vite static sites (React, Vue static builds), use zeabur/caddy-static to serve.
For Vite with SSR frameworks (SvelteKit), use Node.js runtime.

Next.js — Zeabur injects PORT=8080 into the container, so Next.js production mode listens on 8080 by default. No extra config needed.

FROM node:22-slim
LABEL "language"="nodejs"
LABEL "framework"="next.js"
WORKDIR /src
COPY . .
RUN npm install
RUN npm run build
EXPOSE 8080
CMD ["npm", "start"]

Svelte / SvelteKit — Use node:22 (not alpine, not slim). Set ENV PORT=8080. Single-stage build — do NOT use zeabur/caddy-static. Do NOT use cross-env ADAPTER=static or adapter-specific build commands.

FROM node:22
LABEL "language"="nodejs"
LABEL "framework"="svelte"
ENV PORT=8080
WORKDIR /src
RUN npm install -g pnpm@9
COPY . .
RUN pnpm install
RUN pnpm build
EXPOSE 8080
CMD ["pnpm", "start"]

Python

Default base image: python:3.10

Flask — Find the WSGI entry first. For example, if main.py contains app = Flask(__name__), the entry is main:app.

FROM python:3.10
LABEL "language"="python"
LABEL "framework"="flask"
WORKDIR /src
COPY . .
RUN pip install -r requirements.txt gunicorn
EXPOSE 8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "main:app"]

FastAPI — Choose the start method based on what exists:

If fastapi-cli is in requirements.txt → fastapi run
If if __name__ == "__main__": exists in a .py file → python <file>.py
Otherwise → uvicorn main:app --host 0.0.0.0 --port 8080 (install uvicorn if missing)

FROM python:3.10
LABEL "language"="python"
LABEL "framework"="fastapi"
WORKDIR /src
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Generic Python — If WSGI might be applicable, use gunicorn. If unsure, just use python <file>.py.

Go

FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN go build -o /app .

FROM debian:bookworm-slim
LABEL "language"="go"
COPY --from=build /app /app
EXPOSE 8080
CMD ["/app"]

PHP (Laravel / Symfony / Generic)

Uses NGINX + PHP-FPM. Adjust PHP version and extensions as needed.

FROM php:8.3-fpm
LABEL "language"="php"
WORKDIR /var/www
ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
RUN chmod +x /usr/local/bin/install-php-extensions && sync
RUN apt update && apt install -y cron curl gettext git grep libicu-dev nginx pkg-config unzip && rm -rf /var/lib/apt/lists/*
RUN install-php-extensions @composer apcu bcmath gd intl mysqli opcache pcntl pdo_mysql sysvsem zip
RUN cat <<'NGINX' > /etc/nginx/sites-enabled/default
server {
    listen 8080;
    root /var/www;
    index index.php index.html;
    charset utf-8;
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt { access_log off; log_not_found off; }
    error_page 404 /index.php;
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_param PATH_INFO $fastcgi_path_info;
    }
    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }
    location ~ /\.(?!well-known).* { deny all; }
    error_log /dev/stderr;
    access_log /dev/stderr;
}
NGINX
RUN chown -R www-data:www-data /var/www
COPY --chown=www-data:www-data . /var/www
USER www-data
RUN if [ -f composer.json ]; then composer install --optimize-autoloader --classmap-authoritative --no-dev; fi && if [ -f package.json ]; then npm install; fi
USER root
EXPOSE 8080
CMD ["sh", "-c", "php-fpm -D && nginx -g 'daemon off;'"]

For Laravel, add optimization after composer install:

RUN php artisan config:cache && php artisan route:cache && php artisan view:cache

3. Handle Existing Dockerfiles

Analyze the existing Dockerfile first
Use it as-is if it looks correct
Suggest improvements only if there are issues (wrong port, missing dependencies, etc.)
Always add Zeabur-specific labels (language, framework) if missing

CLI Commands

After generating the Dockerfile, deploy with:

npx zeabur@latest deploy --project-id <project-id> --json

For redeployment (must pass service ID to avoid creating duplicates):

npx zeabur@latest deploy --project-id <project-id> --service-id <service-id> --json

Use the zeabur-deploy skill for the full deployment workflow.

Error Handling

If the build or runtime fails:

Check build logs with the zeabur-deployment-logs skill
Common issues:
- Missing dependencies — add to RUN install step
- Wrong port — verify EXPOSE matches what the app listens on; check with zeabur-port-mismatch skill
- Wrong start command — verify CMD matches the project's actual entry point
- Static site served as SSR — switch to zeabur/caddy-static if the app produces static output
- SSR served as static — switch to Node.js runtime if the app requires a server
Fix the Dockerfile, then redeploy with --service-id to update the existing service

zeabur-dockerfile