# Deployments
A deployment is an immutable, timestamped instance of your application running in the container runtime. Each deployment has a unique ID (e.g., `my-app:20241205-1234`), tracks its own status, and can be rolled back to.
## Creating a Deployment
The primary command is `rise deploy`:
```bash
# Deploy from current directory (builds, pushes, deploys)
rise deploy
# Deploy from a specific directory
rise deploy ./path/to/app
# Specify a project explicitly
rise deploy -p my-app
```
`rise deploy` is a shortcut for `rise deployment create` (`rise d c`). After creating the deployment, Rise automatically follows its progress.
### Pre-Built Images
Skip the build step by providing an image directly:
```bash
rise deploy --image nginx:latest --http-port 80
rise deploy --image myregistry.io/my-app:v1.2.3
```
When using `--image`, no build occurs and `--http-port` is required.
> **Note:** Private images from external registries may not be pullable by the container runtime due to missing credentials. Contact your Rise platform administrator for guidance.
### Deploying from an Existing Deployment
Reuse the image from a previous deployment:
```bash
rise deploy --from 20241205-1234
```
By default, the new deployment uses the project's current environment variables. To copy environment variables from the source deployment instead:
```bash
rise deploy --from 20241205-1234 --use-source-env-vars
```
## Deployment Lifecycle
Deployments progress through the following states:
### Build & Deploy States
| `Pending` | Deployment created, waiting to start |
| `Building` | Container image is being built |
| `Pushing` | Image is being pushed to the registry |
| `Pushed` | Image pushed; handoff to the deployment controller |
| `Deploying` | Controller is creating the container in the runtime |
### Running States
| `Healthy` | Running and passing health checks |
| `Unhealthy` | Running but failing health checks |
### Cancellation States (Before Infrastructure)
| `Cancelling` | Being cancelled before infrastructure was provisioned |
| `Cancelled` | Cancelled before infrastructure was provisioned (terminal) |
### Termination States (After Infrastructure)
| `Terminating` | Being gracefully terminated |
| `Stopped` | User-initiated termination (terminal) |
| `Superseded` | Replaced by a newer deployment in the same group (terminal) |
### Other Terminal States
| `Failed` | Could not reach Healthy state (terminal) |
| `Expired` | Auto-deleted after reaching Healthy (terminal) |
## Deployment Groups
Projects can have multiple active deployments using deployment groups.
### Default Group
The `default` group represents the primary deployment:
```bash
rise deploy
# Accessible at: https://my-app.app.example.com
```
### Custom Groups
Create additional deployments with custom group names:
```bash
# Merge request preview
rise deploy --group mr/123 --expire 7d
# Staging environment
rise deploy --group staging
```
Each custom group gets its own URL: `https://{project}-{group}.preview.example.com`
Group names must match `[a-z0-9][a-z0-9/-]*[a-z0-9]` (max 100 characters). When a new deployment in a group reaches `Healthy`, the previous deployment in that group is `Superseded`.
### Auto-Expiration
Set deployments to expire automatically:
```bash
rise deploy --group mr/123 --expire 7d # Days
rise deploy --group preview --expire 24h # Hours
rise deploy --group temp --expire 1w # Weeks
```
Expired deployments are automatically cleaned up.
## Monitoring Deployments
### Following a Deployment
`rise deploy` follows automatically. You can also follow an existing deployment:
```bash
rise deployment show my-app:20241205-1234 --follow
rise d s my-app:latest --follow --timeout 10m
```
### Listing Deployments
```bash
rise deployment list my-app
rise d ls my-app --group staging
```
### Viewing Deployment Details
```bash
rise deployment show my-app:20241205-1234
rise d s my-app:latest
```
### Deployment Logs
```bash
# Show recent logs
rise deployment logs my-app 20241205-1234
# Follow logs in real-time
rise deployment logs my-app 20241205-1234 --follow
# Show last 100 lines
rise deployment logs my-app 20241205-1234 --tail 100
# Show logs since a duration ago
rise deployment logs my-app 20241205-1234 --since 5m
# Show timestamps
rise deployment logs my-app 20241205-1234 --timestamps
```
Note that logs are currently only available for active deployments (`Healthy` or `Unhealthy`) and can not be accessed
for past deployments.
## Rollback
Rollback creates a new deployment using the same image as a previous one:
```bash
rise deployment rollback my-app:20241205-1234
```
This fetches the target deployment's image digest and creates a new deployment with it. The original deployment is not modified.
## Stopping Deployments
Stop all deployments in a group:
```bash
rise deployment stop my-app --group default
rise d stop my-app --group mr/123
```
Stopped deployments remain in the database for rollback purposes.
## Auto-Injected Environment Variables
Rise automatically injects these variables into every deployment:
| `PORT` | HTTP port the container should listen on | `8080` |
| `RISE_ISSUER` | Rise server URL and JWT issuer | `https://rise.example.com` |
| `RISE_APP_URL` | Canonical URL where your app is accessible | `https://myapp.example.com` |
| `RISE_APP_URLS` | JSON array of all URLs where your app is accessible | `["https://myapp.app.example.com", "https://myapp.example.com"]` |
`PORT` defaults to 8080 and can be overridden per-deployment with `--http-port`, or set permanently with `rise env set`. `RISE_APP_URL` is your primary custom domain if set, otherwise the default project URL.
For JWT validation using `RISE_ISSUER`, see [Authentication for Applications](authentication-for-apps.md).
## CI/CD Deployments
For automated deployments from CI/CD pipelines, use service accounts with OIDC workload identity. See [Authentication](authentication.md#service-accounts-workload-identity) for setup instructions and examples for GitLab CI and GitHub Actions.