# Installation

Oban Pro is delivered as a Python package published to our private package repository at
`repo.oban.pro`.

## Prerequisites

Ensure Oban is installed for your application. If not, follow the [Oban installation guide][oi] to
get started.

## Installing the Package

Oban Pro requires authentication with your license key. Grab the `OBAN_LICENSE_KEY` from your
[account page](https://oban.pro/account) and install using one of the methods below.

`````{tab-set}

````{tab-item} Environment Variable
Set the license key as an environment variable:

```bash
export OBAN_LICENSE_KEY="your-license-key"
```

Then install with the `--extra-index-url` flag:

```bash
pip install oban_pro --extra-index-url "https://license:${OBAN_LICENSE_KEY}@repo.oban.pro"
```

Or with uv, set credentials via environment variables:

```bash
export UV_INDEX_OBAN_USERNAME="license"
export UV_INDEX_OBAN_PASSWORD="$OBAN_LICENSE_KEY"
```

Then add from the private index:

```bash
uv add oban_pro --index oban=https://repo.oban.pro
```

To ensure the private index is used only for Oban Pro, mark it as explicit in `pyproject.toml`:

```toml
[[tool.uv.index]]
name = "oban"
url = "https://repo.oban.pro"
explicit = true
```
````

````{tab-item} pip.conf
For persistent configuration, add the repository to your pip configuration file.

**Linux/macOS** (`~/.config/pip/pip.conf` or `~/.pip/pip.conf`):

```ini
[global]
extra-index-url = https://license:YOUR_LICENSE_KEY@repo.oban.pro
```

**Windows** (`%APPDATA%\pip\pip.ini`):

```ini
[global]
extra-index-url = https://license:YOUR_LICENSE_KEY@repo.oban.pro
```

Then install normally:

```bash
pip install oban_pro
```
````

````{tab-item} pyproject.toml
For project-level configuration with uv, add the source to your `pyproject.toml`:

```toml
[[tool.uv.index]]
name = "oban"
url = "https://repo.oban.pro"
explicit = true
```

The `explicit = true` setting ensures that only Oban Pro is fetched from this index, while all other
packages come from PyPI.

Then set the credentials via environment variable:

```bash
export UV_INDEX_OBAN_USERNAME="license"
export UV_INDEX_OBAN_PASSWORD="your-license-key"
```

Or in a `.env` file for local development:

```
UV_INDEX_OBAN_USERNAME=license
UV_INDEX_OBAN_PASSWORD=your-license-key
```

Now install with:

```bash
uv add oban_pro --index oban
```
````

`````

### Authenticating CI/CD and Production

You'll also need to configure authentication on build servers, CI/CD pipelines, and production
deployments. Common approaches include:

- **Docker**: Pass the license key as a build argument or use a `.netrc` file.
- **Actions**: Store `OBAN_LICENSE_KEY` as a repository secret and reference it in your workflow.
- **Cloud**: Use secret management services to inject the environment variable.

```{warning}
Never commit your license key to version control. Use environment variables or secret management
for all environments.
```

## Installing the Schema

Oban Pro extends the base Oban schema with additional tables and functions. After installing the
package, you must run the schema installation to enable features like
[smart concurrency](smart_concurrency.md), [unique jobs](unique_jobs.md), and
[workflows](workflow.md).

`````{tab-set}

````{tab-item} CLI
The simplest approach is to use the CLI:

```bash
obanpro install
```

Or specify the connection string directly:

```bash
obanpro install --dsn "postgresql://user:password@localhost/mydb"
```
````

````{tab-item} Migrations
If you're using a migration framework like Alembic or Django, use the `install_sql` function to
get the raw SQL:

```python
from oban_pro.schema import install_sql

sql = install_sql()
```

For Alembic:

```python
from alembic import op
from oban_pro.schema import install_sql

def upgrade():
    op.execute(install_sql())
```

For Django:

```python
from django.db import migrations
from oban_pro.schema import install_sql

class Migration(migrations.Migration):
    operations = [
        migrations.RunSQL(install_sql()),
    ]
```
````

````{tab-item} Python
You can also install the schema programmatically:

```python
import asyncio

from oban import Oban
from oban_pro.schema import install

async def setup():
    pool = await Oban.create_pool()
    await install(pool)
    await pool.close()

asyncio.run(setup())
```
````

`````

Oban Pro is now installed and ready to use.

## Source Distribution

Oban Pro packages are distributed with encrypted source code to protect intellectual property. This
has no impact on normal usage:

- **Debugging** — Stack traces show correct file names and line numbers
- **LSP Support** — Type stubs provide full autocomplete and type checking
- **Performance** — Decryption happens once at import time

Packages are valid for 30 days from download. Oban Pro never phones home and license validation
happens entirely at build time, ensuring your application runs without communicating with the Oban
Pro servers. Running `uv sync` or `pip install oban_pro` periodically refreshes the package and
ensures continued access.

Enterprise license holders receive unencrypted source for audit requirements or air-gapped
environments. Contact [support](mailto:support@oban.pro) if you need access to unencrypted source.

[oi]: https://oban.pro/docs/py/installation.html