malasaur/deploy repository overview

⁠Deploy

Deploy is a lightweight Docker-based runtime for automatically pulling, building, and serving applications from environment-only configuration.

It is designed to make small deployments simple: give Deploy a source repository or mounted directory, tell it how to build the project, and tell it how to serve it.

⁠Features

• Git repository polling and automatic redeployment
• Local source directories with filesystem watching
• Static website serving
• Long-running application processes
• Automatic builds when source changes
• Private Git repository authentication
• Atomic activation of static releases
• Automatic release retention
• Works with any build/runtime tooling available in the container

⁠How it works

Deploy is organized into independent phases:

INIT → PULL → BUILD → SERVE

Each phase has its own configuration and result, while the runtime orchestrates how they are executed.

The current release focuses on the core deployment lifecycle:

1. PULL gets the source.
2. BUILD prepares the application.
3. SERVE activates the resulting deployment.

Git repositories are checked periodically and only rebuilt when the tracked revision changes.

Local source directories can instead be watched for changes and rebuilt after they become quiet.

⁠Quick start

⁠Static website

services:
  docs:
    image: malasaur/deploy
    ports:
      - "8080:42069"
    environment:
      PULL_FROM: https://github.com/user/docs
      BUILD_COMMAND: uv sync && uv run zensical build
      SERVE_PATH: ./site

Deploy will pull the repository, run the build command, and serve ./site on port 42069 inside the container.

The resulting site is exposed on port 8080 on the host.

Deploy will also poll the repository for updates, every 10 seconds by default. This means if you push a change to the repository, Deploy will automatically rebuild and serve the updated site.

⁠Application process

Deploy can also run a long-lived application process instead of serving static files itself:

services:
  api:
    image: malasaur/deploy
    ports:
      - "8000:8000"
    environment:
      PULL_FROM: https://github.com/user/api
      BUILD_COMMAND: uv sync
      SERVE_COMMAND: uv run python main.py

This assumes the running application listens on 0.0.0.0:8000.

⁠Local source

Deploy can also work with a directory mounted directly into the container:

services:
  site:
    image: malasaur/deploy
    volumes:
      - ./src:/src
    ports:
      - "8080:42069"
    environment:
      BUILD_COMMAND: npm run build
      SERVE_PATH: ./dist

Changes to the mounted source are detected automatically and trigger a new deployment after the configured quiet period.

⁠Configuration

Deploy uses environment variables for configuration.

⁠PULL

For private HTTPS repositories, credentials are supplied securely through Git's authentication mechanism rather than being embedded in the repository URL. .deployignore is a file with .gitignore syntax that lists some files Deploy should ignore. PULL_USE_GITIGNORE also tells Deploy to ignore all files listed in .gitignore.

⁠Build

The command is executed from the deployment's build directory.

⁠Serve

When SERVE_COMMAND is set, Deploy runs in process mode.

When it is not set, Deploy runs in static mode and serves SERVE_PATH itself.