Integrate Upsun with Strapi

These integration guides are not official documentation and the Strapi Support Team will not provide assistance with them.

What Is Upsun?

Upsun is a Git-driven platform as a service (PaaS) that treats your Git repository as the single source of truth for both application code and infrastructure.

Each push spins up an isolated container stack, and you can fork that stack, data and all, into a new preview environment in seconds. Instead of wrestling with fixed hosting tiers, you size resources to the nearest gigabyte or core and pay only for what you actually use through usage-based pricing.

A unified .upsun/config.yaml file defines services, routes, and environment variables for every branch. That configuration travels with your code, which eliminates those "works on my machine" moments and gives you instant production clones that stay current with main.

You will spend less time on DevOps tickets and get faster feedback loops—content designers can test new Strapi collection types in a preview URL while you refine API logic, all without touching production. The team covers this workflow in their Strapi deployment guide.

Upsun runs on Platform.sh technology, inherits its SOC 2 and ISO certifications, and supports multi-cloud regions. For you, that means predictable costs, compliance-ready hosting, and the freedom to iterate without waiting on ops approvals.

Why Integrate with Strapi on Upsun

Combining Strapi v5's API-first content management with Upsun's developer-centric platform lets you iterate fast without babysitting infrastructure. Strapi handles the editorial side—flattened responses, Draft & Publish, granular roles—while Upsun keeps environments, scaling, and costs predictable.

Need to test a risky migration against live data? Spin up a full production clone in seconds. Upsun snapshots the entire stack—database, files, secrets—so you're editing content in an environment that behaves exactly like production. When the experiment is over, deleting the branch tears everything down automatically, saving compute costs and mental overhead. The workflow feels like working locally, only safer.

All orchestration lives in one file: .upsun/config.yaml. This configuration serves as your single source of truth, declaring Node.js version, database service, disk mounts, and cron jobs. Because the file is committed to Git, every branch ships with identical infrastructure, eliminating "works on my machine" problems.

Upsun validates the file on push and shows syntax errors in the build logs, so misconfigurations are caught before they hit reviewers. You can explore the schema in detail in the configuration guide.

Resource tuning is equally granular. Need more memory for a batch image import but only for a day? Bump RAM in the config, push, and Upsun reallocates without touching CPU or disk. When traffic quiets down, dial resources back, and the invoice follows suit. No over-provisioned VMs running in the background.

Preview environments are where content teams really feel the difference. Every pull request gets its own URL—complete with Strapi Admin Panel—thanks to unlimited previews. Editors can verify Draft & Publish flows, marketers can share staging links with stakeholders, and developers can run integration tests, all in parallel, without stepping on each other's toes.

Upsun's usage-based billing means you pay only for active environments and the resources they consume. Paused previews cost mere cents for storage, and budgeting remains straightforward. Combine that with Strapi's open-source license, and you have a stack that scales with your ambition, not your overhead.

How to Deploy Strapi on Upsun

Pushing a Strapi v5 project to Upsun follows a Git-driven workflow powered by a single .upsun/config.yaml file. Whether you're starting from scratch or migrating an existing repo, Upsun's unlimited preview environments and infrastructure-as-code approach streamline the entire deployment process.

Prerequisites

Before your first git push, you'll need an Upsun account with the First Project Incentive activated to keep early costs manageable. Install the Upsun CLI with curl -sS https://installer.upsun.com | bash and authenticate it. You'll also need a Git repository—either empty for new work or your existing Strapi repo—along with Node.js 18 or later on your local machine.

For the Strapi side, you can create a fresh v5 project with npm create strapi@latest my-cms -- --[quickstart](https://docs.strapi.io/cms/quick-start) or work with existing code. You'll want solid familiarity with Git branching, YAML syntax, and environment variables. Understanding Strapi v5 changes like flattened API responses, documentId, and Content History prevents surprises during builds. A general grasp of PaaS concepts—containerized deployments and immutable builds—helps, but isn't strictly necessary.

Setting Up Your Upsun Project

Create a new project using either the web console or CLI. The CLI keeps you in flow:

1upsun project:create

The wizard prompts for project name, region, and Git provider. Once complete, Upsun returns a unique project ID and adds an upsun remote to your repo. Push any branch and Upsun provisions infrastructure automatically using settings from .upsun/config.yaml. Before that first push, set essential secrets like STRAPI_ADMIN_JWT_SECRET and DATABASE_URL:

1upsun variable:set --level=project STRAPI_ADMIN_JWT_SECRET=<redacted>

Configuring the Unified Config File

Every aspect of your deployment lives in .upsun/config.yaml—your single source of truth for building environments. The file has three top-level keys: applications, services, and routes. You'll define the Node.js runtime and build script, persistent disk mounts for media uploads, relationships to managed services like PostgreSQL and Redis, plus resource sizing for CPU, memory, and disk that adjusts per environment.

Environment-specific variables go under runtime.env. Push the branch, watch build logs, and Upsun either validates your YAML or flags errors in red. Fix, commit, push—repeat until green.

Deployment Method 1: Quick Start with New Project

Starting fresh? This path gets you live fastest. First, scaffold locally:

1npx create-strapi@latest my-cms --quickstart
2cd my-cms && git init

Next, create the Upsun project with upsun project:create and note the remote. Then add .upsun/config.yaml at your repo root:

1applications:
2  strapi:
3    type: "node:18"
4    build:
5      commands:
6        - npm install
7        - npm run build
8    disk: 2G
9    mounts:
10      "/srv/app/public/uploads": "uploads"
11    relationships:
12      database: "postgres:pgsql"
13    web:
14      commands:
15        start: "npm run start"
16    limits:
17      cpu: 0.5
18      memory: 512M
19
20services:
21  postgres:
22    type: "postgresql:15"
23    disk: 3G
24
25routes:
26  "/":
27    type: upstream
28    upstream: "strapi:http"

Commit the file, push to main, and watch Upsun build your production-ready environment. Visit the generated URL, create your first admin user, and you're live. For local development parity, pull environment variables:

1upsun project:sync env .env

Upsun handles traffic routing, PostgreSQL provisioning, and persistent storage mounting—no Docker files or Kubernetes YAML required.

Deployment Method 2: Migrating Existing Strapi Projects

Moving an established app? Add Upsun without disrupting your existing pipeline. Start by dropping .upsun/config.yaml into your repo using the template above. Replace hard-coded database strings with environment variables in config/database.js:

1module.exports = ({ env }) => ({
2  connection: {
3    client: 'postgres',
4    connection: env('DATABASE_URL'),
5    ssl: false,
6  },
7});

Commit and push a migration branch. Upsun builds a preview environment so you can verify everything before touching production. Migrate your data by dumping the existing DB and importing via psql over SSH, or use Strapi's Transfer feature. Sync /public/uploads to the persistent disk mount—rsync over SSH usually works best.

Set additional secrets like STRAPI_TRANSFER_TOKEN and OAuth keys with upsun variable:set. Once the preview looks solid, merge to main. Upsun redeploys using the same artifact, so production matches exactly what you tested.

Environment Management and Resource Scaling

Every Git branch becomes an environment—Upsun's core strength. Creating a content-review sandbox takes one command:

1git checkout -b feature/content-api
2git push -u upsun feature/content-api

Upsun clones production data and media into the new environment, giving editors a live preview URL. When traffic spikes, adjust resources instantly:

1upsun environment:update --cpu=1 --memory=1G

Usage-based billing means idle branches auto-pause after 15 days—you won't pay for forgotten compute. For planned campaigns, scale up for the rush, then dial back.

Testing the Deployment

Validation prevents broken CMS builds from reaching production. Hit /admin and log in—if the dashboard loads and you can create content, you're off to a good start. Query a collection at /api/{content-type} and verify Strapi v5's flattened response shape.

Upload a media file and confirm it lands under /srv/app/public/uploads and persists on restart. Tail logs in real time with upsun logs --follow. Need deeper debugging? upsun ssh drops you into the running container. Watch CPU, memory, and latency in the Upsun console—built-in metrics catch regressions before your stakeholders notice.

Project Example: Build an E-commerce Product Catalog

Meet StyleVault, a fictional fashion retailer that uses Strapi v5 for product data while serving a Next.js storefront. Both apps run on Upsun, keeping infrastructure concerns out of the way so teams can focus on launches, not servers.

The stack is straightforward: Strapi exposes product, category, and promotion APIs; Next.js consumes those APIs for static generation and client-side filtering. Upsun creates a full clone for every Git branch, so each seasonal collection gets its own preview URL.

Designers review live product pages before anything reaches production, and editors verify Draft & Publish behavior against real data. When you merge a branch, Upsun tears down the preview automatically—you pay only for the storage that remains.

This is all declared once in a unified configuration file, versioned alongside your code. Push a change, and Upsun parses the YAML, provisions the services, and wires internal networking. No hand-rolled pipelines, no forgotten environment variables.

1# .upsun/config.yaml
2applications:
3  strapi:
4    type: nodejs:18
5    build:
6      commands:
7        - npm install
8        - npm run build
9    disk: 2G
10    relationships:
11      db: "postgresql:db"
12  shop:
13    type: nodejs:18
14    build:
15      commands:
16        - npm install
17        - npm run build
18    commands:
19      start: "npm run start"
20services:
21  db:
22    type: postgresql:14
23    disk: 4G
24routes:
25  "https://{default}/": { type: upstream, upstream: "shop:http" }
26  "https://api.{default}/": { type: upstream, upstream: "strapi:http" }

Practical pain points surface quickly in retail. Holiday sales can triple traffic overnight, so you'll dial CPU and RAM up or down without redeploying—Upsun bills by the hour, not by fixed tiers. Photo-heavy product pages land in Strapi's Media Library; storing originals on an S3-compatible bucket keeps containers stateless and lets you scale horizontally when marketing launches that "last chance" email.

Multiple teams? Give merchandisers their own preview branches while frontend developers ship a new checkout flow on another. Each branch stays isolated, yet all rely on the same configuration, so production surprises become rare.

StyleVault demonstrates how unlimited preview environments, unified configuration, and usage-based scaling can make even high-stakes e-commerce catalog management feel predictably stable.

Strapi Open Office Hours

If you have any questions about Strapi 5 or just would like to stop by and say hi, you can join us at Strapi's Discord Open Office Hours, Monday through Friday, from 12:30 pm to 1:30 pm CST: Strapi Discord Open Office Hours.

For more details, visit the Strapi documentation and Upsun documentation.