# Migration from Legacy Deployment

Migrate from the legacy [stackai-auto-docker](https://github.com/stackai/stackai-auto-docker) deployment to the unified StackAI CLI.

## Prerequisites

* Access to your existing `stackai-auto-docker` deployment
* Your StackAI License Key and Azure Registry credentials
* Root/sudo access on the server

## Migration Steps

{% stepper %}
{% step %}

#### Install the CLI

```bash
curl -sSf https://install.stack.ai | bash
stackai --version
```

{% endstep %}

{% step %}

#### Initialize

```bash
stackai init
```

Follow the prompts to configure your public host, registry credentials, and service URLs.
{% endstep %}

{% step %}

#### Stop Old Deployment

{% hint style="danger" %}
Databases must be stopped before import to prevent corruption.
{% endhint %}

```bash
cd /path/to/stackai-auto-docker
docker compose down
docker ps  # Verify no stackai containers running
```

{% endstep %}

{% step %}

#### Import Data

```bash
cd /path/to/stackai-auto-docker
sudo stackai system import --force
```

Use `--dry-run` first to preview what will be migrated.
{% endstep %}

{% step %}

#### Start and Verify

```bash
stackai deploy start
stackai deploy status
```

Access your domain to verify data migrated correctly.
{% endstep %}
{% endstepper %}

## TLS Certificates

If you have Let's Encrypt certificates:

```bash
sudo cp -L /etc/letsencrypt/live/DOMAIN/fullchain.pem ~/.config/stackai/config/nginx/certs/stackai.crt
sudo cp -L /etc/letsencrypt/live/DOMAIN/privkey.pem ~/.config/stackai/config/nginx/certs/stackai.key
sudo chown $USER:$USER ~/.config/stackai/config/nginx/certs/*
stackai deploy restart nginx
```

## Rollback

Your old deployment is preserved. To rollback:

```bash
stackai deploy stop
cd /path/to/stackai-auto-docker && docker compose up -d
```

***

## FAQ

<details>

<summary>Why does import require sudo?</summary>

Docker volumes (MongoDB, PostgreSQL, etc.) are owned by root. The CLI detects `SUDO_USER` and writes to the correct user directory, then fixes file ownership automatically after import.

</details>

<details>

<summary>What data gets migrated?</summary>

**Data Volumes:**

| Source                                          | Destination                 |
| ----------------------------------------------- | --------------------------- |
| `mongodb/mongodb_data/`                         | `data/mongodb/`             |
| `weaviate/weaviate_data/`                       | `data/weaviate/`            |
| `supabase/volumes/db/data/supabase/postgresql/` | `data/supabase/postgresql/` |
| `supabase/volumes/storage/`                     | `data/supabase/storage/`    |
| `temporalio/volumes/postgres/`                  | `data/temporal/`            |

**Configuration:**

| Source                      | Destination           |
| --------------------------- | --------------------- |
| `stackend/*.toml`           | `config/stackend/`    |
| `nginx/*.conf`              | `config/nginx/`       |
| `supabase/volumes/db/*.sql` | `config/supabase/db/` |

**Environment Variables:**

All `.env` files (`mongodb/`, `supabase/`, `stackend/`, `stackweb/`, `weaviate/`, `unstructured/`) are merged into `~/.config/stackai/.env`. Secrets are encrypted in `secrets.vault`.

</details>

<details>

<summary>How do I renew Let's Encrypt certificates after migration?</summary>

```bash
sudo certbot renew
sudo cp -L /etc/letsencrypt/live/DOMAIN/fullchain.pem ~/.config/stackai/config/nginx/certs/stackai.crt
sudo cp -L /etc/letsencrypt/live/DOMAIN/privkey.pem ~/.config/stackai/config/nginx/certs/stackai.key
stackai deploy restart nginx
```

</details>

<details>

<summary>Can I generate self-signed certificates instead?</summary>

```bash
stackai config tls generate
```

Browsers will show a security warning with self-signed certificates.

</details>

<details>

<summary>How long does migration take for large datasets (50GB+)?</summary>

The import uses staged sync and 8MB buffered I/O for efficiency:

* **10-15 minutes per 100GB** on SSD
* Progress bars show per-volume status
* Most copying happens before services stop, minimizing downtime

</details>

<details>

<summary>MongoDB won't start after migration</summary>

The database was likely running during import, causing journal corruption.

**Fix:**

```bash
stackai deploy stop
rm -rf ~/.config/stackai/data/mongodb/*
cd /path/to/stackai-auto-docker
docker compose down  # Ensure stopped
sudo stackai system import --force
stackai deploy start
```

</details>

<details>

<summary>"CLI not initialized" error during import</summary>

Run `stackai init` before importing. The import command requires the CLI to be fully initialized first.

</details>

<details>

<summary>Permission denied on vault file</summary>

File ownership wasn't fixed properly. Run:

```bash
sudo chown -R $USER:$USER ~/.config/stackai/
```

</details>

<details>

<summary>Port already in use</summary>

Old containers are still running. Stop them:

```bash
cd /path/to/stackai-auto-docker
docker compose down
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stackai.com/stackai-auto-cli/docs/getting-started/migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.