svngoku/coding-agents-skills/scalingo

Scalingo

Scalingo is a European PaaS in the Heroku lineage. You push code (usually via git), the platform builds it with a buildpack, and containers are started according to your Procfile. Managed databases are available as addons. The platform's differentiators are European/French jurisdiction, ISO 27001 / HDS certification, and a region (osc-secnum-fr1) running on SecNumCloud-qualified Outscale infrastructure.

This skill covers the platform end-to-end at a working level: CLI, deployment, addons, scaling, review apps, and IaC. For deep dives on any single topic, consult the references/ files — pointers are given throughout.

When to reach for each reference

The main file stays practical. Pull in a reference when:

• `references/cli-reference.md` — user needs a specific CLI command you don't remember, or wants a full command map
• `references/deployment.md` — deploying via non-git methods (GitHub/GitLab integration, tarball archive, WAR), or configuring auto-deploy
• `references/addons-databases.md` — provisioning, connecting to, or operating a managed database
• `references/scaling-autoscaler.md` — configuring horizontal/vertical scaling or the autoscaler's metric targets
• `references/manifest-review-apps.md` — writing a scalingo.json, configuring review apps, or building a one-click deploy button
• `references/terraform-iac.md` — managing Scalingo resources via the official Terraform provider
• `references/buildpacks.md` — understanding stacks, picking or chaining buildpacks, writing a custom buildpack
• `references/tutorials.md` — deploying a well-known tool (Keycloak, PostgREST, WordPress, n8n, Metabase, ModSecurity WAF, Judoscale, Lovable, Whisper, pgvector, OpenSearch RAG, Elastic Stack) following the official Tutorials Hub

Mental model

Three nouns to internalize:

• App — the unit of deployment. Has a name, a region, environment variables, and a git remote. One app = one deployable project. Apps can be grouped into Projects, which also scope Private Networks.
• Process type — a named command from the Procfile (web, tcp, postdeploy, or anything custom like worker). Each process type runs in one or more containers.
• Addon — a managed service attached to an app (database, cache). Exposes connection details via env vars like SCALINGO_POSTGRESQL_URL.

Everything else — containers, logs, metrics, domains, collaborators — hangs off an app.

Installation and auth

# Install (macOS/Linux)
curl -O https://cli-dl.scalingo.com/install && bash install
 
# Log in (opens a browser)
scalingo login
 
# Or use an API token (for CI/non-interactive)
export SCALINGO_API_TOKEN="tk-us-..."

Set a default region once so you don't repeat --region on every command:

scalingo config --region osc-fr1          # Paris, standard
# OR
scalingo config --region osc-secnum-fr1   # Paris, SecNumCloud infrastructure (sovereign)

Region notes:

• osc-fr1 — default; hosted on Outscale in Paris
• osc-secnum-fr1 — runs on Outscale's SecNumCloud-qualified IaaS; used for French public-sector and sensitive workloads. Access is granted through Scalingo support. The Scalingo PaaS layer itself is not (yet) SecNumCloud-qualified; its qualification is in progress
• List current regions at any time with scalingo regions

Quick start: create and deploy an app

# 1. Create the app (empty, in the default region)
scalingo create my-app
 
# 2. Add the git remote the CLI printed — or ask for it explicitly:
scalingo --app my-app git-show
git remote add scalingo git@ssh.osc-fr1.scalingo.com:my-app.git
 
# 3. Push. master OR main are accepted; other branches need mapping:
git push scalingo main
# git push scalingo feature-x:main   # deploy a different local branch
 
# 4. Watch the build
scalingo --app my-app logs -f

The build detects your stack from files in the repo (Gemfile → Ruby, package.json → Node, requirements.txt/pyproject.toml → Python, etc.) and runs the matching buildpack. Force a buildpack with BUILDPACK_URL if detection is wrong — see references/buildpacks.md.

By default, the web process type scales to 1 × M container. All other process types default to 0 and must be scaled explicitly to start.

The Procfile

A Procfile at repo root declares how each process type starts:

web: gunicorn app:app --bind 0.0.0.0:$PORT
worker: celery -A tasks worker --loglevel=INFO
postdeploy: python manage.py migrate

Reserved process types:

• web — receives HTTP traffic, must bind to $PORT, scaled to 1 by default
• tcp — receives raw TCP traffic through the TCP gateway addon
• postdeploy — runs once per deployment in a separate one-off container (size M, 20-minute limit) after the build and before traffic switches to the new containers; use it for migrations. It replaces the deprecated scripts.postdeploy in scalingo.json

There is no release process type on Scalingo (that's Heroku). Migrations belong in postdeploy.

Everything else is a custom process type — scale it to ≥1 to start it:

scalingo --app my-app scale worker:1:M

Common operations (CLI cheatsheet)

The CLI almost always wants --app <name> (or -a <name>). All commands below assume that flag.

# Apps
scalingo apps                        # list your apps
scalingo create my-app               # create (--project-id to place it in a project)
scalingo --app my-app apps-info      # details (stack, region, status)
scalingo rename --app old --new-name new
scalingo destroy --app my-app        # delete (confirmation required)
 
# Deploy / restart
git push scalingo main               # standard deploy
scalingo --app my-app deploy my-app.tar.gz  # deploy from an archive (local path or URL)
scalingo --app my-app restart                # restart all containers
scalingo --app my-app restart web            # restart one process type
 
# Environment
scalingo --app my-app env                    # list
scalingo --app my-app env-set KEY=value OTHER=value
scalingo --app my-app env-unset KEY
# NOTE: env changes do NOT auto-restart; add `scalingo restart` after bulk changes.
 
# Scaling (amount:size syntax)
scalingo --app my-app scale web:2:L worker:1:M
scalingo --app my-app ps                     # current formation
 
# Logs
scalingo --app my-app logs                   # last lines
scalingo --app my-app logs -f                # stream
scalingo --app my-app logs --lines 500       # historical
 
# One-off containers (copy of production env, destroyed on exit)
scalingo --app my-app run bash               # interactive shell
scalingo --app my-app run --size XL rake db:migrate
scalingo --app my-app run --detached long-job.sh
scalingo --app my-app cron-tasks             # scheduled jobs declared in cron.json (Scalingo Scheduler)
 
# Domains + TLS (Let's Encrypt is automatic; certificates last 45 days and renew automatically)
scalingo --app my-app domains-add example.com
scalingo --app my-app domains                # list
scalingo --app my-app set-canonical-domain example.com
 
# Addons
scalingo --app my-app addons                 # list attached
scalingo --app my-app addons-add postgresql postgresql-starter-512
scalingo --app my-app addons-upgrade <addon-id> postgresql-business-1024
 
# Machine-readable output (global flag; not every command supports it yet)
scalingo --format json --app my-app apps-info

For the full command surface, see references/cli-reference.md.

Environment variables

All configuration belongs in env (12-factor). Scalingo injects addon connection strings automatically — e.g. attaching PostgreSQL gives you SCALINGO_POSTGRESQL_URL and aliases it to DATABASE_URL. Your app reads these at runtime.

scalingo --app my-app env-set DJANGO_SETTINGS_MODULE=myapp.settings.prod

Changing env variables does not trigger a restart. Batch your changes, then scalingo restart.

For multi-line values (TLS keys, JSON blobs), either quote carefully or Base64-encode and decode in-app — the dashboard won't render multi-line values cleanly. Limits: names up to 64 characters, values up to 32,768 characters.

Addons in one minute

# Discover what's available and see plans
scalingo addons-list
scalingo addons-plans postgresql
 
# Attach
scalingo --app my-app addons-add postgresql postgresql-starter-512
 
# Connect from a one-off (uses injected env vars)
scalingo --app my-app pgsql-console
scalingo --app my-app mongo-console
scalingo --app my-app redis-console

Main engines: PostgreSQL, MySQL, MongoDB, Redis (marketed as "Scalingo for Caching"; the addon ID is still redis), OpenSearch, InfluxDB. Elasticsearch is being phased out in favour of OpenSearch, and Sandbox plans can no longer be created. Plans come in service classes: Starter (single node, 98% SLA), Business (multi-node HA, 99.96%), and Enterprise (99.99%, PostgreSQL on Dedicated Resources only, in preview). Always confirm plan IDs with scalingo addons-plans <addon> before using them. Details and sizing guidance: references/addons-databases.md.

scalingo.json (app manifest)

An optional file at repo root that declares how an app should be built when created from a one-click deploy button or as a review app. Minimal shape:

{
  "name": "My App",
  "env": {
    "SECRET_KEY": { "generator": "secret" },
    "PUBLIC_URL": { "generator": "url" }
  },
  "formation": {
    "web":    { "amount": 1, "size": "M" },
    "worker": { "amount": 1, "size": "M" }
  },
  "addons": [
    { "plan": "postgresql:postgresql-starter-512" },
    { "plan": "redis:redis-starter-256" }
  ],
  "scripts": {
    "first-deploy": "bundle exec rake db:migrate db:seed"
  }
}

Triggers for this file: review apps, one-click deploy buttons. It is read only when such an app is created, and not applied on ordinary git push deploys — set the production formation/addons explicitly once. See references/manifest-review-apps.md.

Scaling and the autoscaler

Two dimensions:

• Horizontal — scalingo scale web:3:M (three M-sized web containers). Load is balanced across them.
• Vertical — scalingo scale web:1:XL (upgrade the container tier). Sizes: S / M / L / XL / 2XL / 3XL; 3XL (8 GiB) is the largest and is self-service. Memory doubles per tier: 256 MiB → 512 MiB → 1 GiB → 2 GiB → 4 GiB → 8 GiB. By default a process type can run up to 10 containers.

Swap is being removed: new apps no longer get it since 2026-09-01, and all containers lose it on 2027-01-01. Size containers so the app fits in RAM.

The Scalingo Autoscaler adjusts horizontal scale automatically based on a target metric (cpu, memory, swap, rpm_per_container, p95_response_time, 5XX). It needs a minimum of 2 containers, is keyed by container type (autoscalers-add -c web -m cpu -t 0.75 --min-containers 2 --max-containers 10), and cooldowns prevent flapping (1 min out, 3 min in). Full config and metric guidance: references/scaling-autoscaler.md.

Logs and observability

• Live tail: scalingo --app my-app logs -f
• Router logs (HTTP-level) are off by default — enable in dashboard Routing settings
• Files rotate at 50 MiB to Log Archives (fetch via dashboard or CLI, paginated)
• Ingest caps: 64 MiB/min/container and 16,384 lines/min/container — excess lines are dropped for the rest of the minute
• Archived logs are kept for 1 year
• For retention beyond archives or for search/alerting, configure a Log Drain (syslog/HTTPS/ELK endpoint)

Deployment options beyond git

When git-push isn't the right fit: