Pystrano

Configuration

Pystrano deployment configuration for Django 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 <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.

common:
  source_code_url: "git@github.com:example/example-django-app.git"
  project_root: "apps/example-django-app"
  project_user: "deploy"
  venv_dir: ".venv"
  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 common fields

  • source_code_url: Git repository URL cloned on deploy.
  • 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>/.
  • 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.

Supported server fields

  • host: SSH hostname.
  • port: SSH port. Defaults to 22.
  • run_migrations: Whether to run manage.py migrate during deploy.
  • collect_static_files: Whether to run manage.py collectstatic --noinput 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 requirements.txt, links secrets, optionally runs Django static collection and migrations, promotes the release, restarts the optional service, and removes old releases according to keep_releases.

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.