> ## Documentation Index
> Fetch the complete documentation index at: https://russel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Deploy an example app, update it, roll it back, and remove it, in about five minutes.

You'll deploy `examples/basic-http`, a small Go web server, as a rootless container on your own server. Then you'll redeploy it, roll it back, and remove it.

## Before you start

* Finish [Installation](./getting-started/installation.md): `russel ps` should work, from the server or from your laptop.

## 1. Deploy

```bash theme={null}
russel deploy https://github.com/daschinmoy21/russel.git --config examples/basic-http/Russelfile.toml
```

The control plane clones the repo, reads the Russelfile that `--config` points at, builds the folder it sits in (`examples/basic-http`) with Nix, and starts it. Nothing is cloned on your side, so this works the same from a laptop. The first build takes a minute or two while Nix fetches Go; later deploys take about a second.

When it finishes you'll see something like:

```text theme={null}
  note: container russel-api running. localhost:3100 -> guest:3000

  Test:  curl -I http://127.0.0.1:3100/
```

The service is called `api` because that's the `name` in the example's Russelfile.

## 2. Check it

```bash theme={null}
russel ps
```

```text theme={null}
  ID   RUNTIME    STATUS    STATE    PORTS      UPTIME
  api  container  deployed  running  3100→3000  12s
```

`PORTS` shows host port → app port. Call the app on the host port:

```bash theme={null}
curl http://127.0.0.1:3100/health
# → ok
russel logs api
```

> **Note:** Russel picks a free host port (3100 and up), and an update can move the app to a new one, so use `russel ps` to find it. For a name that stays the same, use [Traefik ingress](./guides/traefik-ingress.md). To keep one port, pin it with `[ingress].port`.

## 3. Update and roll back

After the first deploy, use `russel update` to ship changes. `--refresh` builds the latest commit on the repo's default branch:

```bash theme={null}
russel update api --refresh
```

You can't push to the example repo, so here this rebuilds the same code. With your own app, you push a commit and then run the same command. Without `--refresh`, `update` rebuilds the commit that is already running, which is how you pick up a changed secret.

An update starts the new version next to the old one and switches traffic once the new one answers, so the app keeps serving. The old version keeps running for 2 more seconds. If the new version fails to start, or crashes within those 2 seconds, traffic stays on (or goes back to) the old one and `update` exits non-zero. [When a deploy counts as ready](./concepts/lifecycle.md#when-a-deploy-counts-as-ready) has the details.

Go back to the previous version yourself:

```bash theme={null}
russel rollback api
```

Russel keeps the last 20 deployments. `russel rollback api --version N` picks an older one. More: [Update and rollback](./guides/update-rollback.md).

## 4. Clean up

```bash theme={null}
russel destroy api
```

`russel stop api` stops the app but keeps its history, so a later `update` or `rollback` can bring it back.

Restarting the control plane (`sudo systemctl restart russel-ctrl`) doesn't stop your apps.

## Deploy your own app

```bash theme={null}
cd my-app
russel init        # writes a commented Russelfile.toml
git add Russelfile.toml && git commit -m "Add Russelfile" && git push
russel deploy https://github.com/you/my-app.git
```

The server clones the repo itself, so this works the same from your laptop. After that, push a commit and run `russel update my-app --refresh` to ship it. For a private repo, see [Single-VPS checklist: Deploy from git](./guides/vps-one-dev.md#4-deploy-from-git).

Deploying a folder that is already on the server is off by default. It needs `RUSSEL_ALLOW_LOCAL_PATH_DEPLOY=1` in `/etc/russel/env`; see [First deploy](./getting-started/first-deploy.md#2-deploy).

If your project has no `flake.nix`, Russel generates one for Rust (`Cargo.toml`), Go (`go.mod`), and static sites. `russel init --with-flake` writes a starter flake you can edit instead. See [Builds](./concepts/builds.md) and the [Russelfile reference](./reference/russelfile.md).

## Next steps

* [First deploy](./getting-started/first-deploy.md): deploy from git, and add env vars, secrets, and volumes.
* [Single-VPS checklist](./guides/vps-one-dev.md): run Russel on a VPS and reach apps from the internet.
* [Troubleshooting](./guides/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.