# Soika Mockingjay Installation Guide

## Soika installation via `.deb` (Ubuntu)

This guide installs the Soika backend from the provided `.deb` package and runs it as a `systemd` service.

### Supported OS

* Ubuntu 22.04 / 24.04 (amd64)

### What the `.deb` does

* Installs the Soika release into `/opt/soika/releases/<version>` and updates `/opt/soika/current`.
* Creates a `systemd` service: `soika.service`.
* During install, it can interactively prompt for:
  * Postgres connection info
  * Redis connection info
  * HTTP bind `HOST`/`PORT`
  * `SECRET_KEY`
  * Optional HTTPS setup using **nginx + certbot** (requires those binaries preinstalled)

### 1) Pre-install dependencies

#### A) Base packages

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl systemd
```

#### B) Postgres + pgvector

Install Postgres:

```bash
sudo apt-get update
sudo apt-get install -y postgresql postgresql-contrib
```

Install pgvector (package name can vary by Ubuntu/Postgres version). Try:

```bash
sudo apt-get install -y postgresql-16-pgvector || sudo apt-get install -y postgresql-15-pgvector || true
```

Create database + enable pgvector extension (run as a Postgres superuser):

```bash
sudo -u postgres psql -c "CREATE DATABASE soika;" || true
sudo -u postgres psql -d soika -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

If you use a dedicated DB user/password, create it and grant permissions: The DB user must be the superuser role

```bash
sudo -u postgres psql <<'SQL'
DO $$
BEGIN
  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'soika') THEN
    CREATE ROLE soika LOGIN PASSWORD 'CHANGE_ME';
  END IF;
END $$;
GRANT ALL PRIVILEGES ON DATABASE soika TO soika;
SQL
```

#### C) Redis

```bash
sudo apt-get update
sudo apt-get install -y redis-server
sudo systemctl enable --now redis-server
```

If your Redis requires a password (recommended), set it in `/etc/redis/redis.conf` (or your managed Redis), then restart Redis.

#### D) (Optional) nginx + certbot for HTTPS

If you want HTTPS automation during Soika install, install these first:

```bash
sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx
sudo systemctl enable --now nginx
```

DNS/Firewall requirements for HTTPS:

* Your domain must point to this server’s public IP.
* Inbound **TCP 80** must be reachable for Let’s Encrypt HTTP-01.
* Inbound **TCP 443** must be reachable for HTTPS.

If you do **not** want nginx/HTTPS, you can skip this section and run Soika directly on HTTP.

### 2) Install the Soika `.deb`

From the directory containing the package:

```bash
sudo dpkg -i soika-enterprise_<version>_amd64.deb
```

If `dpkg` reports missing dependencies:

```bash
sudo apt-get -f install -y
sudo dpkg -i soika-enterprise_<version>_amd64.deb
```

During installation you’ll be prompted for Postgres/Redis + bind settings.

### 3) Verify it is running

#### Service status

```bash
sudo systemctl status soika.service --no-pager
```

#### Logs

The `soika.service` unit runs a launcher script; the long-running processes write their logs to files under:

* `/var/log/soika/`

Common log files:

* API: `/var/log/soika/api-error.log`, `/var/log/soika/api-access.log`, `/var/log/soika/api-stdout.log`
* Celery worker: `/var/log/soika/celery-worker.log`
* Celery beat: `/var/log/soika/celery-beat.log`
* Migrations (if enabled via `SOIKA_RUN_MIGRATIONS=1`): `/var/log/soika/migrate.log`

List available logs:

```bash
sudo ls -lah /var/log/soika
```

Tail specific logs:

```bash
sudo tail -n 200 -f /var/log/soika/api-error.log
```

```bash
sudo tail -n 200 -f /var/log/soika/celery-worker.log
```

```bash
sudo tail -n 200 -f /var/log/soika/celery-beat.log
```

```bash
sudo tail -n 200 -f /var/log/soika/migrate.log
```

You can also view the systemd unit logs (mostly startup/shutdown messages):

```bash
sudo journalctl -u soika.service -f
```

Show recent logs:

```bash
sudo journalctl -u soika.service --since "1 hour ago" --no-pager
```

#### Health check

If running on HTTP (no nginx):

```bash
curl -sS http://<'HOST'>:<'PORT'>/health
```

If running behind nginx with HTTPS:

```bash
curl -sS https://YOUR_DOMAIN/health
```

### 4) Common operations

#### Start / stop / restart

```bash
sudo systemctl start soika.service
sudo systemctl stop soika.service
sudo systemctl restart soika.service
```

#### Edit configuration

Soika runtime config:

* `/etc/soika/soika.env`

After edits:

```bash
sudo systemctl restart soika.service
```

### 5) Uninstall (clean removal)

Stop the service:

```bash
sudo systemctl stop soika.service || true
sudo systemctl disable soika.service || true
```

Remove the package:

```bash
sudo apt-get remove --purge -y soika-enterprise
```

Remove leftover directories (optional, deletes config + data + logs):

```bash
sudo rm -rf /etc/soika /opt/soika /var/lib/soika /var/log/soika
```

If you also configured nginx for Soika, remove the site (optional):

```bash
sudo rm -f /etc/nginx/sites-enabled/soika /etc/nginx/sites-available/soika
sudo nginx -t && sudo systemctl reload nginx
```

If you issued a cert with certbot, you can delete it (optional):

```bash
sudo certbot delete --cert-name YOUR_DOMAIN
```


---

# 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://soika-labs.gitbook.io/soika-mockingjay/soika-mockingjay-installation-steps-prerequisites/soika-mockingjay-installation-guide.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.