Getting Started

This guide walks you through everything you need to deploy your first application with Rise, from installation to a running deployment.

Prerequisites

Docker or Podman — required for building container images
- If using Podman Desktop behind a corporate proxy (Zscaler, Cloudflare), you may need to configure SSL certificates. See SSL & Proxy Configuration.
Rise CLI — see installation instructions below

Optional build tools (only needed if you use the corresponding build backend):

pack CLI — for Cloud Native Buildpacks builds. Install docs. With mise: mise use -g ubi:buildpacks/pack
railpack CLI — for Railway Railpacks builds. With mise: mise use -g ubi:railwayapp/railpack

Installing the Rise CLI

With mise (preferred) — downloads a pre-built binary from GitHub releases, no Rust toolchain required:

mise use -g ubi:rise-deploy/rise

With cargo — builds from source (requires Rust):

cargo install rise-deploy

Your platform team may also distribute the rise binary directly — check your internal tooling documentation.

Logging In

rise login --url https://rise.example.com

This opens your browser to complete OAuth2 authentication. After login, the CLI stores your token locally along with the URL, so subsequent commands don’t need --url.

If RISE_URL is already set in your environment (e.g. via your shell profile or a .envrc), you can omit --url:

rise login

You can also set these via environment variables:

RISE_URL — default backend URL
RISE_TOKEN — authentication token (useful for CI/CD; see Authentication)

Creating a Project

A project represents a deployable application. Create one with:

rise project create my-app

This creates the project on the backend and writes a rise.toml file in your current directory. If a rise.toml already exists, only the backend project is created.

You can set the access class and owner:

rise project create my-app --access-class private --owner team:backend

The rise.toml file ties your local directory to the project, so subsequent commands don’t need -p my-app:

[project]
name = "my-app"

See Project Configuration for all options.

Deploying

The primary command for deploying is rise deploy:

rise deploy

This builds a container image from your application, pushes it to the registry, and deploys it. Rise auto-detects the build method based on your project files (Dockerfile, Containerfile, or falls back to buildpacks).

After creating a deployment, Rise automatically follows its progress until it reaches a terminal state.

Deploying a Pre-Built Image

Skip the build step entirely:

rise deploy --image nginx:latest --http-port 80

Deploying to an Environment

Deploy to a specific environment:

rise deploy -E staging

Or deploy to a custom group (e.g., for merge request previews):

rise deploy --group mr/123 --expire 7d

See Deployments for the full lifecycle and Environments for URL routing, variable scoping, and more.

Environment Variables

Set runtime environment variables for your project:

rise env set -p my-app DATABASE_URL postgres://db.example.com/mydb
rise env set -p my-app API_KEY s3cret --secret

List current variables:

rise env list -p my-app
# Or with rise.toml: rise env list

Import from a .env file:

rise env import -p my-app .env

Rise also auto-injects variables like PORT, RISE_ISSUER, RISE_APP_URL, and RISE_APP_URLS into every deployment.

See Environment Variables for secrets, protected secrets, and build-time vs runtime details.

Teams

Create teams and transfer project ownership:

rise team create backend-team --owners alice@example.com --members bob@example.com
rise project update my-app --owner team:backend-team

List teams:

rise team list

Note: Your Rise deployment may restrict team creation to administrators. If rise team create returns a permission error, contact your platform team to create a team or grant you the necessary permissions.

Custom Domains

Add a custom domain to your project:

rise domain add my-app example.com

Configure a DNS CNAME record pointing to your Rise instance, and Rise handles TLS.

Note: Custom domain support depends on how your Rise deployment is configured. Contact your platform team if the command is unavailable or if you need a domain provisioned.

See Custom Domains for details.

Local Development

Run in a container (builds the image, then runs it with project env vars injected):

rise run --project my-app --http-port 3000

Run your app directly with Rise env vars exported to your shell (no image build needed):

rise env export -p my-app > .env.rise
# then load with your preferred tool, e.g.:
export $(cat .env.rise | xargs)
# or: direnv, dotenv, etc.

rise env export fetches the resolved set of non-secret environment variables Rise would inject into a deployment, letting you run your app natively without Docker. This is useful when your local dev workflow builds and runs the app directly (e.g. cargo run, npm run dev).

Note that variables sourced from extensions (e.g., database credentials from the RDS extension) are not included — use a local database for development instead.

See Local Development for port configuration and runtime overrides.

CI/CD

For automated deployments from CI/CD pipelines, use service accounts with OIDC workload identity:

# Production: only protected branches/tags can deploy to production
rise sa create -p my-app \
  --issuer https://gitlab.com \
  --claim aud=https://rise.example.net \
  --claim project_path=myorg/my-app \
  --claim ref_protected=true

# Previews: any branch can deploy, but only to the staging environment
rise sa create -p my-app \
  --issuer https://gitlab.com \
  --claim aud=https://rise.example.net \
  --claim project_path=myorg/my-app

The CI pipeline authenticates with a short-lived OIDC token — no long-lived secrets needed.

Service accounts can be restricted to specific environments (e.g., limit the preview SA to staging so branch deployments never affect the production URL). This separation is strongly recommended: production deployments go to the production environment, while merge-request previews deploy to a staging environment with its own URL and scoped variables. See CI/CD Setup for the full recommended setup.

See Service Accounts for GitLab CI and GitHub Actions examples.

Next Steps

Project Configuration — rise.toml format, build config, precedence rules
Deployments — lifecycle, groups, rollback, logs
Environments — named deployment targets (production, staging, dev)
Building Images — Docker, Pack, Railpack build backends
CI/CD Setup — recommended production + preview SA pattern
Environment Variables — secrets, imports, auto-injected vars
Custom Domains — DNS setup, primary domain
Local Development — rise run, port config
Authentication — login, service accounts, app users
SSL & Proxy Configuration — corporate proxy and certificate handling
CLI Reference — complete command table
Troubleshooting — common issues and solutions