DOCSEARCHbyAlgolia
Submit Docs

devpush Documentation

repository·main·Indexed 26 days ago

https://github.com/hunvreus/devpush

An open-source, self-hostable alternative to Vercel and Netlify. devpush enables Git-based deployments for languages such as Python, Node.js, and PHP using Docker, featuring zero-downtime rollouts, real-time monitoring, and custom domain support. The platform utilizes a microservices architecture consisting of a FastAPI app, arq-based workers, Traefik for routing, PostgreSQL, Redis, and a logging stack with Alloy and Loki.

Tokens
5.8K
Snippets
12
Records
30
Agent score
89%

What's inside devpush

  1. Understand Upgrade Hooks and Update Metadata formats

    main

    The scripts/upgrades/ directory contains versioned files used to manage transitions between versions of the project:

    • Upgrade Hooks: Files named X.Y.Z.sh containing idempotent upgrade steps that must be executed when moving to that specific version.
    • Update Metadata: Files named X.Y.Z.json that provide declarative defaults for the update scope and a user-facing explanation for the update.

  2. Understand the default registry catalog files

    main

    The /dev/push registry folder provides a default catalog snapshot to allow installations to run without network access to a remote registry. It consists of two primary files:

    • catalog.json: A bundled catalog snapshot containing runners, presets, and metadata.
    • overrides.json: A default overrides file used to enable common runners and presets.

    When an instance is initialized, the installer copies these files into DATA_DIR/registry/ if they are not already present. The application then computes a resolved catalog where values in overrides.json take precedence over catalog.json.

  3. Understand the /dev/push architecture and component stack

    main

    /dev/push is a deployment platform built with a microservices architecture. The core components include:

    • App (FastAPI): Handles user logic, authentication, and GitHub webhooks. It serves deployment logs via SSE.
    • Workers:
      • Jobs: Executes deployment tasks (start_deployment, finalize_deployment, etc.) and cleanup using arq.
      • Monitor: Polls running deployments every ~2s to detect success or failure.
    • Traefik: Reverse proxy that routes traffic to the app and user-deployed runner containers using Docker labels and dynamic configuration.
    • Data Layer: Uses PostgreSQL for primary storage and Redis for the arq job queue and real-time UI updates via Redis Streams.
    • Logging: Runner logs are collected by Alloy, stored in Loki, and streamed to users via the app.
    • Runtime: User applications run in isolated Runner Containers managed via a Docker Socket Proxy.

  4. Quickstart: Install /dev/push on a fresh server

    main

    To install /dev/push on a fresh Ubuntu or Debian server, run the installation script via curl.

    Prerequisites:

    • Ubuntu 20.04+ or Debian 11+
    • SSH access and sudo privileges
    • A GitHub account (to create a GitHub App)
    • An email provider (Resend or SMTP credentials)
    curl -fsSL https://install.devpu.sh | sudo bash

  5. Set up DNS for /dev/push

    main

    To ensure the application and its deployments are accessible, configure your DNS provider (e.g., Cloudflare) with the following records:

    1. An A record for your app hostname (e.g., example.com) pointing to your server IP.
    2. A wildcard A record for deployments (e.g., *.example.com) pointing to your server IP.

  6. Manage services using operational scripts

    main

    The project provides helper scripts for managing components in local and production environments. These scripts support component-scoped operations using the --components <csv> flag.

    Available Scripts

    • start.sh: Starts services.
    • stop.sh: Stops services.
    • restart.sh: Restarts services.
    • update.sh: Updates services. By default, it only updates the app. To widen the scope, use one of the following flags:
      • --all: Update all components.
      • --components <csv>: Update specific components.
      • --full: Perform a full update.
      • --metadata <path>: Use metadata from scripts/upgrades/*.json to define the update scope.

  7. Set up /dev/push for local development

    main

    To run /dev/push locally for development, you need Docker and Docker Compose v2+. On macOS, Colima is recommended.

    1. Clone the repository.
    2. Create the data directory.
    3. Copy the example environment file.
    4. Edit the .env file with your GitHub App credentials.
    5. Start the stack using the provided script.
    git clone https://github.com/hunvreus/devpush.git
cd devpush
mkdir -p data
cp .env.dev.example data/.env
# Edit data/.env with your GitHub App credentials
./scripts/start.sh

  9. Configure the default registry via overrides.json

    main

    To enable or disable specific entries in the registry, or to change specific fields within the catalog, edit the overrides.json file located in DATA_DIR/registry/.

    Important: Do not edit catalog.json directly on the server. To make permanent changes to the catalog, use the official sync flow. Use overrides.json for local instance configuration and overrides.

  10. Configure /dev/push environment variables

    main

    After installation, you must configure the service by editing the /var/lib/devpush/.env file. You will need to provide the following keys:

    • APP_HOSTNAME: The hostname for the application.
    • DEPLOY_DOMAIN: The domain used for deployments.
    • LE_EMAIL: Email for Let's Encrypt SSL certificates.
    • EMAIL_SENDER_ADDRESS: The address used for sending emails.
    • RESEND_API_KEY: Your Resend API key (if using Resend).
    • GitHub App credentials (required for login and repository access).

  11. Understand the deployment lifecycle and status flow

    main

    Deployments follow a specific state machine managed by the Jobs and Monitor workers:

    1. Trigger: Initiated via GitHub Webhook (/api/github/webhook) or manual user action.
    2. prepare (start_deployment): Creates the runner container, clones the repo, and runs build/start commands. Status is set to in_progress.
    3. deploy: The container is running. The Monitor worker probes the container IP on devpush_runner:8000/.
    4. finalize (finalize_deployment): Triggered on successful probe. Sets status to completed and conclusion=succeeded. It also regenerates Traefik dynamic configuration for aliases and domains.
    5. completed / fail:
      • On success: status=completed, conclusion=succeeded.
      • On error/exit: conclusion=failed (or canceled/skipped).

    Deployment Statuses Summary:

    • prepare $\rightarrow$ deploy $\rightarrow$ finalize $\rightarrow$ completed.
    • Conclusions: succeeded, failed, canceled, or skipped.

  12. Configure ACME challenge provider for Let's Encrypt

    main

    When setting up SSL/TLS via Let's Encrypt, you can specify the CERT_CHALLENGE_PROVIDER to use DNS-01 challenges. This is useful for wildcard certificates.

    Supported values:

    • default: Uses HTTP-01 challenge.
    • cloudflare, route53, gcloud, digitalocean, azure: Uses the specified provider for DNS-01 challenges.