Pystrano

Configuration

Pystrano deployment configuration for Django and FastAPI apps, environments, and servers.

Where the config file lives

By default, Pystrano reads:

deploy/<app_name>/<environment_name>/deployment.yml

The general CLI shape is:

pystrano <init|setup|deploy> <environment> <app>

You can override the config root and filename:

pystrano deploy production api \
  --deploy-config-dir ./ops/deploy \
  --config-file-name pystrano.yml

Environments

The environment is the middle directory name. For example, deploy/api/staging/deployment.yml and deploy/api/production/deployment.yml are separate environments for the same app.

Common variables and server overrides

A config contains a common section and a servers list. Values in common apply to each server. Values on a server override common values for that server.

config_version: 2

common:
  source_code_url: "git@github.com:example/example-django-app.git"
  framework: "django"
  project_root: "apps/example-django-app"
  project_user: "deploy"
  venv_dir: ".venv"
  package_manager: "pip"
  dependency_file: "requirements.txt"
  keep_releases: 5
  system_packages: |
    libpq-dev
    python3-dev
    build-essential
  env_file: "./deploy/api/production/.env"
  ssh_known_hosts: "github.com"
  service_file: "./deploy/api/production/gunicorn.service"
  secrets: "./deploy/api/production/django-secret-key.txt"
  branch: "main"
  clone_depth: 1

servers:
  - host: "app1.example.com"
    port: 22
    run_migrations: true
    collect_static_files: true

  - host: "app2.example.com"
    run_migrations: false
    collect_static_files: true

Supported config fields

  • config_version: Pystrano config format version. Version 2 configs should declare 2; missing or older values produce a runtime compatibility warning.
  • source_code_url: Git repository URL cloned on deploy.
  • framework: Deployment workflow. Supported values are django and fastapi. Defaults to django.
  • project_root: Project path under /home/<project_user>/.
  • project_user: Remote user that owns and deploys the app.
  • venv_dir: Virtualenv path under /home/<project_user>/.
  • package_manager: Dependency installer. Supported values are pip and uv. Defaults to pip.
  • dependency_file: Dependency file used during install. Defaults to requirements.txt for pip and uv.lock for uv.
  • dependency_install_command: Optional exact dependency install command. When set, Pystrano runs it instead of the built-in pip or uv command.
  • keep_releases: Number of release directories to keep. Use 0 or less to keep all.
  • system_packages: Extra apt packages installed during setup.
  • env_file: Local dotenv file copied to the server shared directory during deploy.
  • ssh_known_hosts: Semicolon-separated hosts added with ssh-keyscan during setup.
  • service_file: Optional local systemd service file copied during setup.
  • secrets: Optional semicolon-separated local files copied during setup and linked into releases.
  • branch: Git branch cloned during deploy.
  • clone_depth: Shallow clone depth. Use 0 or less for a full clone.
  • revision: Optional tag, SHA, or ref checked out after cloning. When set, Pystrano uses a full clone.
  • migration_command: FastAPI migration command. Defaults to <venv_dir>/bin/alembic upgrade head.
  • static_files_command: FastAPI static files command. Required when framework: fastapi and collect_static_files: true.

Supported server fields

  • host: SSH hostname.
  • port: SSH port. Defaults to 22.
  • run_migrations: Whether to run the framework migration step during deploy.
  • collect_static_files: Whether to run the framework static files step during deploy.

Deployment path

After config is loaded, Pystrano builds the remote project path as:

/home/<project_user>/<project_root>

It then uses these release-oriented paths:

/home/<project_user>/<project_root>/releases
/home/<project_user>/<project_root>/current
/home/<project_user>/<project_root>/shared

Shared files and directories

Pystrano creates a shared directory, links shared/media into each release, copies each deploy's dotenv file into the shared directory, and links configured secret files into the release. The current implementation does not expose a generic custom shared-files list beyond env_file, secrets, and the built-in media link.

Setup steps

pystrano setup connects as root, creates the deploy user, copies authorized keys, creates the project directory structure, installs base and configured packages, creates the virtualenv, updates known hosts, registers the optional systemd service, and uploads optional secret files.

Deploy steps

pystrano deploy connects as project_user, creates a timestamped release, clones source code, copies the environment file, links shared assets, installs dependencies with the configured package manager, links secrets, optionally runs framework-specific static collection and migrations, promotes the release, restarts the optional service, and removes old releases according to keep_releases.

Dependency installation

For package_manager: pip, Pystrano runs <venv_dir>/bin/pip install -r <dependency_file>. For package_manager: uv with dependency_file: uv.lock, Pystrano ensures uv exists in the virtualenv, then runs uv sync --frozen --no-dev with UV_PROJECT_ENVIRONMENT set to the virtualenv. With uv and another dependency file, Pystrano runs uv pip install against the configured file.

Framework steps

Django deployments use manage.py collectstatic --noinput and manage.py migrate when the matching server flags are enabled. FastAPI migrations default to <venv_dir>/bin/alembic upgrade head; use migration_command to override that and static_files_command for any FastAPI static build step.

Rollback-related config

keep_releases controls how many old release directories remain available. Pystrano does not currently expose a rollback command, so keep enough releases for your manual recovery window.