Sub2API

Deploy and Host Sub2API on Sealos

Sub2API is a self-hosted AI API gateway for managing upstream accounts, API keys, quotas, routing, and usage. This template deploys Sub2API with PostgreSQL, Redis, persistent storage, public HTTPS access, and optional private S3-compatible storage on Sealos Cloud.

About Hosting Sub2API

Sub2API provides one control plane for connecting AI service subscriptions and exposing managed API access to users or internal applications. Administrators can operate upstream accounts, groups, subscriptions, billing policies, API keys, usage records, and service health from the web console.

The template provisions the full runtime stack. PostgreSQL stores application data, Redis provides cache and coordination services, and a persistent volume stores /app/data. A startup init container generates and persists the Sub2API TOTP encryption key in that volume before the application starts. A dependency gate starts Sub2API after both data services accept connections, while Sealos supplies the public domain and TLS certificate.

Sub2API also documents S3-compatible storage for asynchronous image task results. Enabling the storage option creates a private Sealos object-storage bucket and injects its managed endpoint and credentials directly into the application.

Common Use Cases

• Unified AI Gateway: Route supported AI clients through one managed endpoint.
• Account and Quota Operations: Pool upstream accounts and distribute capacity across users or groups.
• API Key Management: Issue keys, control access, and review usage from one console.
• Subscription Operations: Manage plans, balances, redemption codes, and billing policies.
• Async Image Workflows: Store generated image results in a private S3-compatible bucket.

Dependencies for Sub2API Hosting

The template includes Sub2API 0.1.166, PostgreSQL 16.4.0, Redis 7.2.7, persistent volumes, HTTPS ingress, and an optional Sealos object-storage bucket.

Deployment Dependencies

• Sub2API repository - Source code and upstream documentation
• Sub2API v0.1.166 release - Container version used by this template
• Asynchronous image task documentation - S3-compatible image result storage
• PostgreSQL documentation - Database reference
• Redis documentation - Redis reference
• Sealos documentation - Platform documentation

Implementation Details

Architecture Components

• Sub2API: One StatefulSet replica running weishaw/sub2api:0.1.166 on port 8080.
• Dependency gate: A resource-capped init container waits for the dedicated sub2api PostgreSQL database and the Redis endpoint.
• TOTP key bootstrap: A startup init container creates a 64-character lowercase hexadecimal key at /app/data/.totp_encryption_key and reuses it for the application process.
• Application storage: A 1Gi persistent volume mounted at /app/data.
• PostgreSQL: One KubeBlocks PostgreSQL 16.4.0 component with 1Gi persistent storage.
• Database initialization: An idempotent Job creates the sub2api database after PostgreSQL becomes available.
• Redis: A KubeBlocks Redis 7.2.7 replication topology with one Redis component and one Sentinel component, each with persistent storage.
• Object storage: An optional private ObjectStorageBucket for asynchronous image task results.
• Public access: A Sealos-managed HTTPS Ingress and Canvas application entry.

Resource Profile

Template Inputs

The template generates a fixed per-deployment JWT_SECRET and a cryptographically random 64-character lowercase hexadecimal TOTP_ENCRYPTION_KEY on first startup. The TOTP key is stored at /app/data/.totp_encryption_key with restrictive file permissions and reused across Pod restarts. Database and object-storage credentials come from Sealos-managed Secrets.

Health and Storage Behavior

• GET /health reports application health on port 8080.
• AUTO_SETUP=true initializes the database and creates the first administrator.
• The startup key bootstrap persists the TOTP encryption key in /app/data before Sub2API starts.
• The optional S3 branch sets IMAGE_STORAGE_ENABLED=true, uses path-style access, and stores image objects under images/.
• The default local branch sets IMAGE_STORAGE_ENABLED=false.
• The bucket policy is private, so application-generated signed URLs control object access.

Why Deploy Sub2API on Sealos?

• Single Deployment Flow: Launch the application, data services, storage, and ingress together.
• Managed Credentials: Sealos creates database and object-storage credentials and injects them into the correct workloads.
• Persistent Data: PostgreSQL, Redis, and application data use persistent volumes.
• Optional Object Storage: A form toggle adds private S3-compatible storage for documented image workflows.
• Public HTTPS Endpoint: Sealos provides the domain, ingress, and TLS certificate.
• Canvas Operations: Inspect logs, resource health, storage, and configuration from one deployment view.

Deployment Guide

1. Open the Sub2API template and click Deploy Now.
2. Enter admin_email and an admin_password with at least 8 characters.
3. Choose the timezone and run mode. Enable enable_s3_storage when asynchronous image results should use a private Sealos bucket.
4. Add provider OAuth, URL allowlist, or update proxy values that match your environment.
5. Start the deployment and wait for PostgreSQL, Redis, the database initialization Job, and Sub2API to become healthy. This usually takes several minutes.
6. Open the application URL shown in Canvas.

Login and User Onboarding

1. Open the application URL. Sub2API displays the sign-in page.
2. Sign in with the exact admin_email and admin_password entered during deployment.
3. On the first administrator session, read the deployment and operations compliance notice, type the acknowledgement phrase displayed by Sub2API, and continue to the dashboard.
4. Create managed users from Users > Create User. Public registration policy is available in the application settings.

The initial administrator is created during first startup. Reusing an existing data volume keeps the administrator stored in PostgreSQL.

Configuration

Use the Sub2API console for upstream accounts, groups, subscriptions, API keys, usage, announcements, and service settings. Use Sealos Canvas for workload resources, persistent volumes, logs, domains, and environment configuration.

When S3 storage is enabled, the application receives the private bucket configuration automatically. The Admin > Backup page shows the effective asynchronous image storage settings and connection test.

Scaling

The validated starting profile targets an idle or evaluation deployment. Increase Sub2API CPU and memory in Canvas as traffic, concurrent requests, background work, or account volume grows.

Keep the current application replica count while /app/data uses a single ReadWriteOnce volume. Review Sub2API storage and session requirements before designing a multi-replica deployment.

Troubleshooting

The application URL is still starting

PostgreSQL and Redis initialization can take several minutes. Check both KubeBlocks clusters, the PostgreSQL init Job, and the Sub2API StatefulSet in Canvas.

Administrator login fails

Use the email and password entered in the deployment form. The password is case-sensitive and requires at least 8 characters.

The dashboard remains behind the compliance prompt

Enter the acknowledgement phrase exactly as displayed, including its language and spacing.

Async image storage is unavailable

Confirm that enable_s3_storage was enabled for the deployment. In Sub2API, open Admin > Backup, review the image storage configuration, and run its connection test.

A raw object URL returns an authorization error

This is expected for the private bucket. Access image results through the application-provided signed URL flow.

Getting Help

• Sub2API issues
• Sealos documentation
• Sealos Discord

License

Sub2API is licensed under the GNU Lesser General Public License v3.0 or later. This Sealos template is distributed under the license of the templates repository.