Sub2API

https://github.com/wei-shaw/sub2api
Admin
Sub2API is an AI API gateway platform that distributes and manages API quotas from subscriptions,...
Tokens:134,331
Snippets:1,017
Trust Score:9
License:LGPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Start Sub2API service and open Setup Wizard

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

Post-installation commands to start the Sub2API service, enable auto-start on boot, and open the Setup Wizard in a browser at http://YOUR_SERVER_IP:8080. The Setup Wizard guides you through database configuration, Redis configuration, and admin account creation.

```bash
# 1. Start the service
sudo systemctl start sub2api

# 2. Enable auto-start on boot
sudo systemctl enable sub2api

# 3. Open Setup Wizard in browser
# http://YOUR_SERVER_IP:8080
```

--------------------------------

### Manual Installation - Enable and Start Service

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

Manual installation step 4: reload systemd, enable and start the sub2api service after copying the binary and service file.

```bash
sudo systemctl daemon-reload
sudo systemctl enable sub2api
sudo systemctl start sub2api
```

--------------------------------

### Manual Deployment Setup with Docker Compose

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

Manual setup steps: clone the repository, copy the environment template, set permissions, and edit the .env file. Requires Docker 20.10+ and Docker Compose v2+.

```bash
# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. Copy environment configuration
cp .env.example .env
chmod 600 .env

# 3. Edit configuration (generate secure passwords)
nano .env
```

--------------------------------

### One-Line Installation

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

One-line installation for production servers using systemd. Downloads and executes the install script with sudo.

```bash
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash
```

--------------------------------

### Binary Install Troubleshooting Commands

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

Use these commands to troubleshoot a binary installation. They check the service status, view recent logs, inspect the config file, and verify PostgreSQL and Redis services.

```bash
# Check service status
sudo systemctl status sub2api

# View recent logs
sudo journalctl -u sub2api -n 50

# Check config file
sudo cat /etc/sub2api/config.yaml

# Check PostgreSQL
sudo systemctl status postgresql

# Check Redis
sudo systemctl status redis
```

--------------------------------

### Run the application

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

Run the application with `./sub2api` after completing the setup steps.

```bash
# 6. Run the application
./sub2api
```

--------------------------------

### Start Services with Docker Compose (Local or Named Volumes)

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

Steps to create data directories and start services using either the local directory version (recommended for easy migration) or the named volumes version. Includes checking status and viewing logs.

```bash
# 4. Create data directories (for local version)
mkdir -p data postgres_data redis_data

# 5. Start all services
# Option A: Local directory version (recommended - easy migration)
docker compose -f docker-compose.local.yml up -d

# Option B: Named volumes version (simple setup)
docker compose up -d

# 6. Check status
docker compose -f docker-compose.local.yml ps

# 7. View logs
docker compose -f docker-compose.local.yml logs -f sub2api
```

--------------------------------

### Install Script Commands

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

Commands for installing, upgrading, and uninstalling sub2api using the install script.

```bash
# Install
sudo ./install.sh

# Upgrade
sudo ./install.sh upgrade

# Uninstall
sudo ./install.sh uninstall
```

--------------------------------

### Start services and view logs after running the deployment script

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

Commands to start the Docker services, view logs, and find the auto-generated admin password. Access the Web UI at http://localhost:8080.

```bash
# Start services
docker compose -f docker-compose.local.yml up -d

# View logs
docker compose -f docker-compose.local.yml logs -f sub2api

# If admin password was auto-generated, find it in logs:
docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

# Access Web UI
# http://localhost:8080
```

--------------------------------

### Store Test/Reset Example

Source: https://github.com/wei-shaw/sub2api/blob/main/frontend/src/stores/README.md

Shows how to reset auth and app stores for testing: logout for auth, reset for app.

```typescript
// Auth store
authStore.logout() // Clears all auth state

// App store
appStore.reset() // Resets to defaults
```

--------------------------------

### Verify Apple container CLI version

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/APPLE_CONTAINER.md

Verify the Apple container CLI is installed and its version is 1.1.0 or newer. Run this before proceeding with the guided setup.

```bash
container --version
```

--------------------------------

### Get generated admin password from app logs

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/APPLE_CONTAINER.md

Retrieve the generated admin password from the application container logs when ADMIN_PASSWORD is empty. Use after starting the stack with ./apple-container.sh up.

```bash
./apple-container.sh logs app
```

--------------------------------

### Create admin account by moving config.yaml aside

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

Temporarily move an existing `config.yaml` aside so the setup wizard can trigger on first run, then restore it afterwards. The wizard runs at `http://localhost:8080` and writes a fresh config; stop the server with Ctrl+C once it completes, then restore and restart in normal mode.

```bash
mv config.yaml config.yaml.bak
./sub2api        # wizard runs at http://localhost:8080 and writes a fresh config.yaml
# stop the server (Ctrl+C) once the wizard completes, then restore your config:
mv config.yaml.bak config.yaml
./sub2api        # restart in normal mode and log in with the admin you just created
```

--------------------------------

### App Store Usage Example (useAppStore)

Source: https://github.com/wei-shaw/sub2api/blob/main/frontend/src/stores/README.md

Demonstrates using the app store for sidebar control, loading state, toast notifications, and custom toast handling.

```typescript
import { useAppStore } from '@/stores'

// In component setup
const appStore = useAppStore()

// Sidebar control
appStore.toggleSidebar()
appStore.setSidebarCollapsed(true)

// Loading state
appStore.setLoading(true)
// ... do work
appStore.setLoading(false)

// Or use helper
await appStore.withLoading(async () => {
  const data = await fetchData()
  return data
})

// Toast notifications
appStore.showSuccess('Operation completed!')
appStore.showError('Something went wrong!', 5000)
appStore.showInfo('FYI: This is informational')
appStore.showWarning('Be careful!')

// Custom toast
const toastId = appStore.showToast('info', 'Custom message', undefined) // No auto-dismiss
// Later...
appStore.hideToast(toastId)
```

--------------------------------

### signature.json example

Source: https://github.com/wei-shaw/sub2api/blob/main/backend/pkg/pluginapi/docs/package-format.md

Example of the signature.json file. The signature object is the exact raw bytes of manifest.json. The algorithm is ed25519, key_id identifies the publisher key, and signature is a Base64-encoded signature.

```json
{
  "algorithm": "ed25519",
  "key_id": "publisher-key-id",
  "signature": "BASE64_SIGNATURE"
}
```

--------------------------------

### Upgrade Apple Runtime (Down, Stop, Start, Up)

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/APPLE_CONTAINER.md

Shell commands to upgrade the Apple container runtime itself. Used when installing/updating Apple container 1.1.0 or newer. Stops the container system and starts it again.

```bash
./apple-container.sh down
container system stop
# Install/update Apple container 1.1.0 or newer.
container system start
./apple-container.sh up
```

--------------------------------

### Manual Docker deployment steps

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

Manual deployment process: clone the repository, configure the environment, generate secure secrets, create data directories, and start services.

```bash
# Clone repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# Configure environment
cp .env.example .env
chmod 600 .env
nano .env  # Set POSTGRES_PASSWORD and other required variables

# Generate secure secrets (recommended)
JWT_SECRET=$(openssl rand -hex 32)
TOTP_ENCRYPTION_KEY=$(openssl rand -hex 32)
echo "JWT_SECRET=${JWT_SECRET}" >> .env
echo "TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY}" >> .env

# Create data directories
mkdir -p data postgres_data redis_data

# Start all services using local directory version
docker compose -f docker-compose.local.yml up -d

# View logs (check for auto-generated admin password)
docker compose -f docker-compose.local.yml logs -f sub2api

# Access Web UI
# http://localhost:8080
```

--------------------------------

### Startup log warning: image_storage.enabled is true but object storage not fully configured

Source: https://github.com/wei-shaw/sub2api/blob/main/docs/ASYNC_IMAGE_TASKS.md

Shows the exact warning logged at startup when the image_storage configuration is incomplete, preventing async image tasks from being enabled. The missing_keys field names the credentials that were empty.

```text
WARN image_storage.enabled is true but object storage is not fully configured; async image tasks are disabled  missing_keys=[...]
```

--------------------------------

### Download and run the one-click deployment script

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/README.md

Downloads and executes the docker-deploy.sh script, which prepares the environment by downloading compose files, generating secrets, and creating data directories. The script displays generated credentials after running.

```bash
# Download and run the preparation script
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# Or download first, then run
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh -o docker-deploy.sh
chmod +x docker-deploy.sh
./docker-deploy.sh
```

--------------------------------

### Example Migration: Add tier_id to Gemini OAuth Accounts

Source: https://github.com/wei-shaw/sub2api/blob/main/backend/migrations/README.md

Example migration that adds a tier_id field to Gemini OAuth accounts for quota tracking. It uses jsonb_set to set the tier_id to 'LEGACY' only for rows where it is currently NULL.

```sql
-- Add tier_id field to Gemini OAuth accounts for quota tracking
UPDATE accounts
SET credentials = jsonb_set(
    credentials,
    '{tier_id}',
    '"LEGACY"',
    true
)
WHERE platform = 'gemini'
  AND type = 'oauth'
  AND credentials->>'tier_id' IS NULL;
```

--------------------------------

### Initialize Stores in main.ts

Source: https://github.com/wei-shaw/sub2api/blob/main/frontend/src/components/layout/INTEGRATION.md

Sets up the Vue app with Pinia and the router, and initializes the auth state by calling checkAuth() on startup.

```typescript
// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'
import './style.css'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)
app.use(router)

// Initialize auth state on app startup
import { useAuthStore } from '@/stores'
const authStore = useAuthStore()
authStore.checkAuth()

app.mount('#app')
```

--------------------------------

### Deploy Sub2API stack with apple-container.sh

Source: https://github.com/wei-shaw/sub2api/blob/main/deploy/APPLE_CONTAINER.md

Clone the repository deterministically, then use apple-container.sh init to generate a .env with random PostgreSQL, JWT, and TOTP secrets. Optionally edit .env with nano, then run up to create volumes/network/containers and start Sub2API, and status to verify PostgreSQL, Redis, and the application endpoint. Requires Apple container 1.1.0 or newer and openssl.

```bash
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# Creates .env with random PostgreSQL, JWT, and TOTP secrets.
./apple-container.sh init

# Review optional settings before startup.
nano .env

# Creates volumes/network/containers, waits for dependencies, and starts Sub2API.
./apple-container.sh up

# Verifies PostgreSQL, Redis, and the application endpoint.
./apple-container.sh status
```

--------------------------------

### Quick Start with Docker Compose Deployment Script

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

One-click deployment using the automated script. Downloads docker-compose.local.yml (saved as docker-compose.yml) and .env.example, generates secure credentials (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD), creates .env with auto-generated secrets, and creates data directories. Displays generated credentials for reference.

```bash
mkdir -p sub2api-deploy && cd sub2api-deploy

# Download and run deployment preparation script
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# Start services
docker compose up -d

# View logs
docker compose logs -f sub2api
```

--------------------------------

### LoadingSpinner.vue usage example

Source: https://github.com/wei-shaw/sub2api/blob/main/frontend/src/components/common/README.md

Shows how to use the LoadingSpinner component with size and color props.

```vue
<LoadingSpinner size="lg" color="primary" />
```

--------------------------------

### GET /v1/images/batches/{id}/download

Source: https://github.com/wei-shaw/sub2api/blob/main/docs/BATCH_IMAGE_MVP.md

Download all generated outputs for the batch as a ZIP file.

```APIDOC
## GET /v1/images/batches/{id}/download

### Description
Download all generated outputs for the batch as a ZIP file.

### Method
GET

### Endpoint
/v1/images/batches/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The batch job ID.

### Response
#### Success Response (200)
- The response is a ZIP file containing the batch's generated images.

#### Response Example
Binary ZIP file
```

--------------------------------

### Run development mode with hot reload

Source: https://github.com/wei-shaw/sub2api/blob/main/README.md

Start the backend and frontend in development mode with hot reload. Backend uses `go run ./cmd/server`; frontend uses `pnpm run dev`.

```bash
# Backend (with hot reload)
cd backend
go run ./cmd/server

# Frontend (with hot reload)
cd frontend
pnpm run dev
```

--------------------------------

### GET /v1/images/batches/{id}

Source: https://github.com/wei-shaw/sub2api/blob/main/docs/BATCH_IMAGE_MVP.md

Retrieve the status and metadata for a specific batch job identified by its ID.

```APIDOC
## GET /v1/images/batches/{id}

### Description
Retrieve the public batch response for a given batch job ID.

### Method
GET

### Endpoint
/v1/images/batches/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The batch job ID (e.g., 'imgbatch_...').

### Response
#### Success Response (200)
- **id** (string) - Batch job ID.
- **object** (string) - "image.batch".
- **status** (string) - Status, e.g., "queued".
- **model** (string) - Model used.
- **provider** (string) - Provider used.
- **item_count** (integer) - Number of items in the batch.
- **success_count** (integer) - Number of successful items.
- **fail_count** (integer) - Number of failed items.
- **estimated_cost** (number) - Estimated cost.
- **actual_cost** (number or null) - Actual cost.
- **created_at** (integer) - Creation timestamp.
- **submitted_at** (integer) - Submission timestamp.
- **settled_at** (integer or null) - Settlement timestamp.

#### Response Example
{
  "id": "imgbatch_0123456789abcdef0123456789abcdef",
  "object": "image.batch",
  "status": "queued",
  "model": "gemini-2.5-flash-image",
  "provider": "gemini_api",
  "item_count": 1,
  "success_count": 0,
  "fail_count": 0,
  "estimated_cost": 0.25,
  "actual_cost": null,
  "created_at": 1783123200,
  "submitted_at": 1783123201,
  "settled_at": null
}
```

--------------------------------

### TypeScript Types Import Example

Source: https://github.com/wei-shaw/sub2api/blob/main/frontend/src/stores/README.md

Shows importing the User, Toast, and ToastType types from the @/types module.

```typescript
import type { User, Toast, ToastType } from '@/types'
```
Tokens:
Raw