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

# Overview

> Deploy 2501 on your infrastructure

Deploy and configure 2501 on your infrastructure using the `2501 infra` CLI.

## Install the CLI

Install the `2501 infra` CLI on the machine that will run the deployment. Your 2501 account team provides the installer. Installation is a single self-contained step: it places a checksum-verified static binary, sets up a sudo wrapper so `2501 infra deploy` runs privileged without you typing `sudo`, and runs a non-interactive setup so you finish with a ready-to-edit workspace. No Docker, AWS CLI, or registry login is required on the machine to install.

Common installer options: `--target kubernetes` (instead of the default Docker Swarm), `--user` (install under your home directory with no sudo), and `--version <tag>` (pin a specific version).

### Keeping the CLI current

There is no separate update command. The CLI stays in lockstep with the deployed platform version:

* **During deploy.** Interactive `2501 infra deploy` lists published releases newest-first. When you pick a version, the CLI self-updates its own binary to match (checksum-verified, then re-executed) before deploying.
* **CLI only.** To refresh just the binary, re-run the installer. It is idempotent and never touches an existing workspace.

## Quick start

After install, you typically only need to edit two environment files before deploying.

<Steps>
  <Step title="Edit the engine environment">
    Open `/etc/2501/env.engine` and set the human-required values, such as your LLM provider API keys and the external `DATABASE_URL`.
  </Step>

  <Step title="Edit the Command Center environment">
    Open `/etc/2501/env.command-center` and confirm its values.
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    2501 infra deploy
    ```

    `deploy` syncs your env files to the current version's spec, runs database migrations, and brings up the stack.
  </Step>
</Steps>

<Note>
  Most settings are defaulted for you. A plain Docker Swarm deployment with an external database needs no configuration file at all, just the two environment files above. See [Configuration](/0.12/deployment/configuration) for when an optional `2501-infra.yml` is written.
</Note>

## Upgrading

Upgrading is the same `deploy` command at a newer version. Point your Kubernetes manifests and/or `2501-infra.yml` at the new image tag, depending on how you deployed, then apply. The Engine, the Command Center, and the executor images the Engine spawns all move to that tag together.

Read the [release notes](https://www.2501.ai/changelog) for every version you are crossing before you start. Some releases add environment variables or carry breaking changes, which matters most when you are coming from an old version.

<Warning>
  Back up PostgreSQL first, schema and data both:

  ```bash theme={null}
  pg_dump "$DATABASE_URL" --format=custom --file=2501-preupgrade.dump
  ```

  Restoring that dump is what makes a downgrade possible. An Elasticsearch snapshot is optional.

  Keep automated backups for disaster recovery too, not just one dump before an upgrade. This matters most when 2501 manages PostgreSQL for you, rather than connecting to a database you already run and already back up.
</Warning>

Commands worth knowing around an upgrade:

| Command                       | What it gives you                                                                             | Targets              |
| ----------------------------- | --------------------------------------------------------------------------------------------- | -------------------- |
| `2501 infra status`           | Running services, with configured against deployed versions and a warning when they disagree. | Swarm and Kubernetes |
| `2501 infra logs`             | Service logs, for when something does not come back up.                                       | Swarm and Kubernetes |
| `2501 infra deploy --history` | The last 10 deployments, newest first. The current tag is your rollback target.               | Swarm only           |

On Kubernetes the CLI generates manifests rather than applying them, so it does not record what reached the cluster. Take your rollback target from the image tag in your manifests or from your GitOps history instead.

Once the new version is up, check both health endpoints at the address your containers are exposed on:

```bash theme={null}
curl http://<engine-host>:<engine-port>/health
curl http://<command-center-host>:<command-center-port>/health
```

<Note>
  The interactive version picker reads the release list from `https://2501-public.s3.eu-west-3.amazonaws.com/cli-2501/versions.json`. Allow egress to it if you want the picker; otherwise pass `--tag <version>` explicitly.
</Note>

### Rolling back

If the new version misbehaves, go back to the last one that worked and restore the data that went with it:

* Redeploy the previous image tag.
* Restore your PostgreSQL backup. If the failed upgrade already part-migrated the database, recreate it empty and restore into that.
* Verify the stack is healthy before handing it back to users.
* Contact 2501 with what went wrong and any details you still have, so we can debug it and ship a patch.

A restore rewinds your data to the moment the backup was taken.

## Getting help

The CLI includes built-in documentation for all commands:

```bash theme={null}
# List all commands
2501 infra -h

# Help for specific commands
2501 infra deploy -h
2501 infra config -h
2501 infra tenant -h
2501 infra org -h
2501 infra user -h
```

## Deployment workflow

1. **Install** the `2501 infra` CLI (setup runs automatically)
2. **Edit** `env.engine` and `env.command-center` with your human-required values
3. **Deploy** with `2501 infra deploy`
4. **Create entities** (the CLI prompts you interactively; skipped with `--yes`)
5. **Access** the Command Center UI

## What's Next

<CardGroup cols={2}>
  <Card title="Init Command" icon="terminal" href="/0.12/deployment/init-command">
    Initialize your deployment
  </Card>

  <Card title="Configuration" icon="gear" href="/0.12/deployment/configuration">
    Overview of configuration files
  </Card>

  <Card title="Docker Swarm" icon="server" href="/0.12/deployment/docker-swarm">
    Deploy to production
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/0.12/deployment/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>