Skip to main content
Upsun is a cloud hosting platform that builds, deploys, and scales your applications automatically. This guide walks you through deploying your first project—from installing the CLI to seeing your app live in production. The entire process takes about 10-15 minutes.

​
Before you begin

You need:
  • An Upsun account (sign up for free)
  • A supported runtime (Node.js, PHP, Python, Go, Java, Ruby, or .NET)
  • Git installed locally
  • Basic command-line familiarity

​
Choose your path

Pick the situation that matches yours and we’ll take you straight to the right guide.

Start from zero

No project yet? Install the CLI, spin up a new project, and deploy your first app.

Bring your project

Got an app? Add one YAML file to your repo, push to Upsun, and you’re live.

Connect your repo

Already on GitHub? Link GitHub, GitLab, or Bitbucket. Every PR auto-deploys to a live preview.

Deploy AI & agents

Building with AI? Deploy AI agents, LLM-powered apps, or MCP servers.

​
Get started quickly

The steps below follow the “Start from zero” path—creating a new project from scratch and deploying it to Upsun. If you already have an existing application or want to connect a Git repository, choose the appropriate card above instead. Follow these steps to go from zero to a live Upsun deployment as fast as possible.
1

Install the Upsun CLI

Install the CLI for your operating system.
brew install platformsh/tap/upsun-cli
Then log in to your Upsun account:
upsun login
Full setup guide · CLI reference
2

Create your first project

Create a new Upsun project using the Console (Create project → Start from scratch) or the CLI:
upsun project:create
Full guide · Open console ↗
3

Add your config file

Run upsun init to generate .upsun/config.yaml, which defines your app’s runtime, services, and routes.If your project uses services (such as a database or caching service), upsun init also generates an executable .environment script. See the full guide below for details.
.upsun/config.yaml
applications:
  myapp:
    type: 'nodejs:22'
    hooks:
      build: 'npm install && npm run build'

services:
  db:
    type: 'postgresql:16'

routes:
  'https://{default}/':
    type: upstream
    upstream: 'myapp:http'
Full guide · Node.js · PHP · Python
4

Set CPU, RAM & disk

Configure resources for your app with upsun resources:set:
upsun resources:set --size myapp:1
Full guide · Resource docs
5

Push and go live

Commit your configuration and push to deploy:
git add .upsun/config.yaml
git commit -m "Add Upsun configuration"
upsun push
Full guide
6

Develop locally

Open a tunnel to connect your local environment to live Upsun services:
upsun tunnel:open
npm run dev
Full guide · Tethered setup
7

Connect your Git provider (optional)

Optional: Link GitHub, GitLab, or Bitbucket to mirror, build, and auto-deploy on every push:
upsun integration:add --type github --repository myorg/myapp
This step is optional—you can continue using upsun push directly. Source integrations are recommended for team workflows and CI/CD automation.Full guide

​
What’s next

Now that you have a live deployment, explore these key topics to make the most of Upsun:

Manage environments

Create branches, preview environments, and manage your development workflow.

Scale resources

Adjust CPU, RAM, and disk allocation to match your application’s needs.

Add a custom domain

Configure your production domain and SSL certificates.

Monitor & debug

View logs, metrics, and application performance data.
Last modified on April 13, 2026