🚦 Trafic

DDEV preview environments on any Linux server.

Trafic turns a VPS into a preview server for your web projects. It handles authentication, scale-to-zero, auto-start, and deployments from CI — all powered by DDEV and Traefik.

Features

• DDEV-native — No custom Dockerfiles needed. Works with WordPress, Laravel, Drupal, and any DDEV-compatible project.
• Scale-to-zero — Idle projects are stopped automatically to save RAM. They restart on the next request.
• Authentication — Forward auth via Traefik with IP whitelist, tokens, basic auth, and per-hostname rules.
• Preview environments — Create and destroy environments from CI, like Vercel but for PHP.
• Backups on removal — destroy --backup dumps the database and upload directories first.
• Scheduled removal — destroy --delay 48h keeps a preview for a while; a new deploy cancels it.
• Running limit — max_running_projects caps how many projects run at once.
• Simple CLI — setup (server), deploy (CI), destroy (cleanup).
• TOML config — Simple, readable configuration.
• Zero vendor lock-in — Runs on any Linux VPS with SSH access.

How it works

flowchart TD
  request[HTTPS request] --> traefik[Traefik / DDEV router]
  traefik --> forwardAuth[forwardAuth → trafic agent]
  forwardAuth --> |200 OK| ddev-web[DDEV project]
  forwardAuth --> |401| basic-auth[Basic auth prompt]
  traefik --> |502 error| errors[errors middleware → trafic agent]
  errors --> |known project| waiting[Waiting page + auto-start]
  errors --> |unknown project| error-page[Error page]
  errors --> |project being removed| removing[Error page 503]

Loading

Quick start

# Setup a server over SSH (run from your machine or from CI)
npx @studiometa/trafic-cli setup \
  --host=server.example.com \
  --tld=previews.example.com \
  --email=admin@example.com

# …or run it on the server itself, as root
npx @studiometa/trafic-agent setup --tld=previews.example.com --email=admin@example.com

# Deploy from CI
npx @studiometa/trafic-cli deploy \
  --host=server.example.com \
  --name=my-app \
  --branch=main \
  --sync="dist/" \
  --script="composer install --no-dev"

# Your app is live at https://my-app.previews.example.com

Packages

Package	Description	npm
@studiometa/trafic-cli	CLI for deploying projects from CI
@studiometa/trafic-agent	Server agent (auth, scale-to-zero)

Requirements

Server:

• Ubuntu 24.04 LTS
• Root access, or a user with passwordless sudo (for initial setup)
• Wildcard DNS (*.previews.example.com → server IP)

CI:

• Node.js 24+
• SSH access to the server

CI examples

GitLab CI

deploy_preview:
  stage: deploy
  image: node:24
  before_script:
    - chmod 600 "$SSH_PRIVATE_KEY"
  script:
    - npx @studiometa/trafic-cli deploy
        --host $SSH_HOST
        --name $CI_PROJECT_PATH_SLUG
        --preview $CI_MERGE_REQUEST_IID
        --ssh-options="-i $SSH_PRIVATE_KEY -o IdentitiesOnly=yes"
        --sync "dist/"
        --script "composer install --no-dev"
  rules:
    - if: $CI_MERGE_REQUEST_ID

destroy_preview:
  stage: deploy
  image: node:24
  when: manual
  before_script:
    - chmod 600 "$SSH_PRIVATE_KEY"
  script:
    - npx @studiometa/trafic-cli destroy
        --host $SSH_HOST
        --name $CI_PROJECT_PATH_SLUG
        --preview $CI_MERGE_REQUEST_IID
        --ssh-options="-i $SSH_PRIVATE_KEY -o IdentitiesOnly=yes"
  rules:
    - if: $CI_MERGE_REQUEST_ID

SSH_PRIVATE_KEY is a file-type CI variable. Do not use ssh-agent in GitLab CI: see the CLI README.

GitHub Actions

deploy_preview:
  runs-on: ubuntu-latest
  if: github.event_name == 'pull_request'
  steps:
    - uses: actions/checkout@v4
    - uses: webfactory/ssh-agent@v0.9.0
      with:
        ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
    - run: npx @studiometa/trafic-cli deploy
        --host ${{ vars.SSH_HOST }}
        --name ${{ github.event.repository.name }}
        --preview ${{ github.event.pull_request.number }}
        --sync "dist/"
        --script "composer install --no-dev"

destroy_preview:
  runs-on: ubuntu-latest
  if: github.event_name == 'pull_request' && github.event.action == 'closed'
  steps:
    - uses: webfactory/ssh-agent@v0.9.0
      with:
        ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
    - run: npx @studiometa/trafic-cli destroy
        --host ${{ vars.SSH_HOST }}
        --name ${{ github.event.repository.name }}
        --preview ${{ github.event.pull_request.number }}

Agent skills

Two Agent Skills teach a coding agent to use Trafic:

• trafic-cli: write and fix the CI jobs that run trafic setup, trafic deploy and trafic destroy.
• trafic-agent: operate the server (setup, upgrade, audit, destroy, config.toml).

Install them in a project or for your user:

npx skills add studiometa/trafic
# or, with the GitHub CLI
gh skill install studiometa/trafic

Each package also prints the skill that matches its version: trafic skill and trafic-agent skill.

Documentation

• CLI README — Deploy and destroy commands
• Agent README — Server setup and configuration
• Example config — Full configuration reference

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT © Studio Meta