# Deploy and Host New API on Sealos

New API is a next-generation LLM gateway and AI asset management system that exposes a unified OpenAI-compatible API. This template deploys New API as a single persistent application backed by KubeBlocks-managed PostgreSQL and Redis on Sealos Cloud.

![New API Logo](./logo.png)

## About Hosting New API

New API sits between your applications and upstream AI providers, giving you one endpoint for model routing, quota control, channel orchestration, and operational visibility. It helps teams standardize provider access while keeping user, token, and channel management in one web console.

This Sealos template provisions the application runtime together with PostgreSQL, Redis, persistent storage, HTTPS ingress, and the database bootstrap job. The result is a ready-to-run deployment that keeps application data and logs durable across restarts while exposing the service through a Sealos-managed public URL.

## Common Use Cases

- **Unified OpenAI-Compatible Gateway**: Route requests from multiple model providers through one stable API endpoint.
- **Team Quota Management**: Manage users, channels, quotas, and access rules from a central dashboard.
- **Provider Fallback and Traffic Steering**: Shift traffic across vendors without changing client-side integrations.
- **Internal AI Platform**: Offer a shared gateway for engineering, product, or operations teams inside your own cluster.
- **Self-Hosted Model Operations**: Keep gateway state, credentials, and routing policies under your own infrastructure control.

## Dependencies for New API Hosting

The Sealos template includes all required dependencies for running New API:

- New API application container
- PostgreSQL 16.4 provided by KubeBlocks
- Redis 7.2.7 provided by KubeBlocks
- PostgreSQL init job for the `new-api` database
- Kubernetes `StatefulSet`, `Service`, and `Ingress`
- Persistent storage for `/data` and `/app/logs`

### Deployment Dependencies

- [New API Documentation](https://docs.newapi.pro/) - Official documentation and product overview
- [Environment Variables Reference](https://docs.newapi.pro/en/docs/installation/config-maintenance/environment-variables) - Runtime configuration reference
- [API Documentation](https://docs.newapi.pro/en/docs/api) - OpenAI-compatible and provider-specific API docs
- [New API GitHub Repository](https://github.com/QuantumNous/new-api) - Source code and issue tracking
- [Community Interaction](https://docs.newapi.pro/en/docs/support/community-interaction) - Community and support channels

### Implementation Details

**Architecture Components:**

This template deploys the following services:

- **New API StatefulSet** (`calciumion/new-api:v0.13.2`): Serves the web UI and OpenAI-compatible API on port `3000`
- **PostgreSQL Cluster**: Stores users, channels, quotas, and application configuration
- **Redis Cluster**: Provides cache and Redis-backed runtime state
- **PostgreSQL Init Job**: Waits for database readiness and creates the `new-api` database idempotently, using the same small Sealos resource ladder as the application container
- **Service, Ingress, and App Resources**: Publish the application over Sealos-managed HTTPS

**Configuration:**

- `SQL_DSN` is composed from the KubeBlocks secret `${{ defaults.app_name }}-pg-conn-credential`.
- `REDIS_CONN_STRING` is built from `${{ defaults.app_name }}-redis-redis-account-default` and the internal Redis service DNS.
- `SESSION_SECRET` and `CRYPTO_SECRET` are generated by default so the deployment starts with stable runtime secrets.
- Health checks target `/api/status`, and persistent volumes are mounted at `/data` and `/app/logs`.
- The application and init containers use `200m` CPU / `256Mi` memory limits with `20m` CPU / `25Mi` memory requests. Each application PVC requests `103Mi`, which passed live cold-start validation for the application data and log directories.

**License Information:**

New API is licensed under the [GNU Affero General Public License v3.0](https://github.com/QuantumNous/new-api/blob/main/LICENSE). The upstream project also notes that organizations with commercial licensing concerns can contact the maintainers directly.

## Why Deploy New API on Sealos?

Sealos is an AI-assisted Cloud Operating System built on Kubernetes, so you get Kubernetes-grade deployment primitives without maintaining the manifests and operational wiring yourself. For New API, that means the gateway, database, cache, storage, and public HTTPS entrypoint are delivered as one packaged template.

By deploying New API on Sealos, you get:

- **One-Click Deployment**: Launch the full stack from a template instead of assembling PostgreSQL, Redis, ingress, and storage by hand.
- **Managed Kubernetes Foundation**: Run on standard Kubernetes resources with service discovery, stable storage, and controlled rollouts.
- **Easy Customization**: Change resources and configuration later through Canvas, AI dialog, and resource cards.
- **Persistent Storage Included**: Keep application data and logs durable across pod restarts and upgrades.
- **Instant Public HTTPS Access**: Expose the UI and API through a Sealos-managed ingress with TLS enabled.
- **Pay-As-You-Go Efficiency**: Start with a small footprint and scale resources only when traffic or data size requires it.

## Deployment Guide

1. Open the [New API template](https://sealos.io/products/app-store/new-api) and click **Deploy Now**.
2. Configure the deployment parameters in the popup dialog:
   - `app_host`
   - `app_name`
   - `session_secret`
   - `crypto_secret`
3. Wait for deployment to complete, which typically takes 2-3 minutes. After deployment, you will be redirected to Canvas. For later changes, describe the update in AI dialog or use the relevant resource cards.
4. Access New API at `https://<app_host>.<SEALOS_CLOUD_DOMAIN>`. On first launch, the setup wizard checks PostgreSQL, asks you to create the root administrator account, asks you to choose a usage mode, and then initializes the system. After setup, sign in at `/login` with the administrator username and password you created.

## Configuration

After deployment, you can configure New API through:

- **Web UI**: Add providers, channels, quotas, groups, and runtime settings from the dashboard
- **AI Dialog**: Ask Sealos AI to adjust resource sizes or template-backed settings
- **Resource Cards**: Open the application, PostgreSQL, Redis, ingress, or storage cards to make targeted changes

### Template Parameters

| Parameter | Description | Default |
| --- | --- | --- |
| `app_host` | Public hostname prefix for the New API ingress | `new-api-<random>` |
| `app_name` | Kubernetes resource name prefix for the deployment | `new-api-<random>` |
| `session_secret` | Session secret used by New API | Random 32-character value |
| `crypto_secret` | Encryption secret used for Redis-backed encrypted state | Random 32-character value |

### Operational Notes

- Keep `session_secret` stable if you reuse the same deployment state.
- Keep `crypto_secret` stable if Redis-backed encrypted data is already in use.
- The init job creates the `new-api` PostgreSQL database only when it does not already exist.
- The template is intentionally single-replica by default. Validate your own session and runtime behavior before increasing replicas.

## Scaling

To scale New API on Sealos:

1. Open the deployment in Canvas.
2. Click the New API `StatefulSet` resource card.
3. Adjust CPU and memory requests or limits as needed.
4. Apply the change and monitor the rollout.

For stateful components, scale PostgreSQL and Redis separately through their own resource cards if your workload requires it. Keep the application replica count at `1` unless you have validated your own multi-replica strategy.

## Troubleshooting

### Common Issues

**Issue: Setup or login behaves inconsistently after a redeploy**
- Cause: `SESSION_SECRET` changed after the initial deployment.
- Solution: Restore the original secret value and restart the application pod.

**Issue: Redis-backed encrypted data cannot be decrypted**
- Cause: `CRYPTO_SECRET` changed while encrypted data already exists in Redis.
- Solution: Restore the original `crypto_secret` value before restarting the workload.

**Issue: The application starts but database initialization fails**
- Cause: PostgreSQL was not ready when the app first attempted to start, or the init job did not complete successfully.
- Solution: Check the `${{ defaults.app_name }}-pg-init` job status and the PostgreSQL cluster health in Canvas, then retry the application rollout if needed.

### Getting Help

- [New API Documentation](https://docs.newapi.pro/)
- [New API GitHub Issues](https://github.com/QuantumNous/new-api/issues)
- [FAQ](https://docs.newapi.pro/en/docs/support/faq)
- [Sealos Documentation](https://sealos.io/docs)
- [Sealos Discord](https://discord.gg/wdUn538zVP)

## Additional Resources

- [New API Project Overview](https://docs.newapi.pro/en/docs/introduction)
- [Installation Documentation](https://docs.newapi.pro/en/docs/installation)
- [API Documentation](https://docs.newapi.pro/en/docs/api)
- [Environment Variables Reference](https://docs.newapi.pro/en/docs/installation/config-maintenance/environment-variables)

## License

This Sealos template is provided under the license policy of the Sealos templates repository. New API itself is licensed under the [GNU Affero General Public License v3.0](https://github.com/QuantumNous/new-api/blob/main/LICENSE).