# 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](ssl-proxy.md).
- **Rise CLI** — the `rise` binary (obtain from your platform team or build from source with `cargo build --bin rise`)

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

- **pack CLI** — for Cloud Native Buildpacks builds. [Install docs](https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/). With mise: `mise use -g ubi:buildpacks/pack`
- **railpack CLI** — for Railway Railpacks builds. With mise: `mise use -g ubi:railwayapp/railpack`

## Logging In

```bash
rise login
```

This opens your browser to complete OAuth2 authentication. After login, the CLI stores your token locally.

To connect to a specific Rise instance:

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

You can also set these via environment variables:

- `RISE_URL` — default backend URL
- `RISE_TOKEN` — authentication token (useful for CI/CD; see [Authentication](authentication.md))

## Creating a Project

A project represents a deployable application. Create one with:

```bash
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:

```bash
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`:

```toml
[project]
name = "my-app"
access_class = "public"
```

See [Project Configuration](configuration.md) for all options.

## Deploying

The primary command for deploying is `rise deploy`:

```bash
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:

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

### Deploying to a Custom Group

Deploy preview or staging environments alongside production:

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

Custom groups get their own URL (e.g., `https://my-app-mr-123.preview.example.com`) and can auto-expire.

See [Deployments](deployments.md) for the full lifecycle, deployment groups, rollback, and more.

## Environment Variables

Set runtime environment variables for your project:

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

List current variables:

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

Import from a `.env` file:

```bash
rise env import 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](environment-variables.md) for secrets, protected secrets, and build-time vs runtime details.

## Teams

Create teams and transfer project ownership:

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

List teams:

```bash
rise team list
```

## Custom Domains

Add a custom domain to your project:

```bash
rise domain add my-app example.com
```

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

See [Custom Domains](custom-domains.md) for details.

## Local Development

Build and run your application locally with project environment variables:

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

This builds the image, loads non-secret env vars from the project, and runs the container interactively.

See [Local Development](local-development.md) for port configuration and runtime overrides.

## CI/CD

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

```bash
# Create a service account for GitLab CI
rise sa create my-app \
  --issuer https://gitlab.com \
  --claim aud=rise-project-my-app \
  --claim project_path=myorg/my-app \
  --claim ref_protected=true
```

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

See [Authentication](authentication.md#service-accounts-workload-identity) for GitLab CI and GitHub Actions examples.

## Next Steps

- **[Project Configuration](configuration.md)** — `rise.toml` format, build config, precedence rules
- **[Deployments](deployments.md)** — lifecycle, groups, rollback, logs
- **[Building Images](builds.md)** — Docker, Pack, Railpack backends
- **[Environment Variables](environment-variables.md)** — secrets, imports, auto-injected vars
- **[Custom Domains](custom-domains.md)** — DNS setup, primary domain
- **[Local Development](local-development.md)** — `rise run`, port config
- **[Authentication](authentication.md)** — login, service accounts, app users
- **[SSL & Proxy Configuration](ssl-proxy.md)** — corporate proxy and certificate handling
- **[CLI Reference](cli-reference.md)** — complete command table
- **[Troubleshooting](troubleshooting.md)** — common issues and solutions
