How to Configure Vercel Deployment for DS2API

Deploy DS2API to Vercel by forking the CJackHwang/ds2api repository, importing it into Vercel, setting the DS2API_ADMIN_KEY environment variable, and letting the platform automatically build the hybrid Go and Node runtimes defined in vercel.json.

DS2API is a DeepSeek API proxy that runs on Vercel using a unique hybrid architecture combining Go and Node.js serverless functions. Configuring Vercel deployment for DS2API requires understanding how the vercel.json configuration file orchestrates the build pipeline and how environment variables handle runtime settings. This guide provides the exact steps and configuration options available in the CJackHwang/ds2api source code.

Fork and Import the Repository

Vercel requires write access to deploy, so you must first fork the repository to your own GitHub account. Once forked, import the repository into Vercel by creating a New Project and selecting your fork.

Vercel automatically detects the vercel.json file at the repository root and reads the build configuration. According to the source code, the build process compiles the WebUI and bundles the Go binary using the following command defined in vercel.json:

{
  "buildCommand": "npm ci --prefix webui && npm run build --prefix webui",
  "outputDirectory": "static"
}

This command installs WebUI dependencies, builds the frontend, and prepares the static directory for deployment.

Configure Environment Variables

Environment variables control the runtime behavior of DS2API on Vercel. Navigate to Project Settings → Environment Variables in the Vercel dashboard to configure the following:

Required Variables

• DS2API_ADMIN_KEY – A strong secret key required to access the admin UI at /admin.

Optional Configuration

• DS2API_CONFIG_JSON – Complete configuration as a single-line Base64 string. If omitted, DS2API starts with an empty configuration that you can populate later via the admin UI.

• VERCEL_TOKEN, VERCEL_PROJECT_ID, VERCEL_TEAM_ID – Required only if you want to use the built-in "Vercel Sync" UI feature to push configuration changes back to Vercel automatically.

Runtime Tuning Variables

You can fine-tune performance using these optional variables:

• DS2API_ACCOUNT_MAX_INFLIGHT – Per-account concurrent request limit (default: 2).
• DS2API_ACCOUNT_MAX_QUEUE – Queue size per account (defaults to recommended_concurrency).
• DS2API_GLOBAL_MAX_INFLIGHT – Global concurrency limit (defaults to recommended_concurrency).
• DS2API_VERCEL_STREAM_LEASE_TTL_SECONDS – Lease TTL for streaming sessions (default: 900).
• DS2API_VERCEL_INTERNAL_SECRET – Internal authentication for Go-to-Node communication (falls back to admin key if unset).
• DS2API_VERCEL_PROTECTION_BYPASS – Secret to bypass Vercel Deployment Protection for internal API calls.
• DS2API_ENV_WRITEBACK – When set, writes the configuration back to a file after successful sync.

Prepare the Configuration Payload

To deploy with a pre-configured setup, convert your local config.json to a Base64 string before adding it to Vercel.

Generate Base64 Configuration

From the repository root, run:

# Prepare your configuration file first

cp config.example.json config.json

# ... edit config.json with your DeepSeek accounts ...

# Convert to Base64

DS2API_CONFIG_JSON=$(base64 < config.json | tr -d '\n')
printf "%s\n" "$DS2API_CONFIG_JSON"

Copy the printed Base64 string and paste it into the Vercel Environment Variables as DS2API_CONFIG_JSON. If you leave this variable empty, DS2API will start with an empty configuration; you can later import a JSON file via the admin UI at /admin and use the Vercel Sync page to write the Base64 value back to Vercel automatically.

Understand the Hybrid Runtime Architecture

DS2API on Vercel uses a dual-runtime approach defined in vercel.json:

• api/index.go – The Go serverless function that provides the core API logic and handles standard HTTP requests.
• api/chat-stream.js – A Node.js wrapper that manages real-time Server-Sent Events (SSE) streaming.

The vercel.json file contains specific routing rules that direct traffic between these runtimes:

{
  "functions": {
    "api/chat-stream.js": { "maxDuration": 300 },
    "api/index.go": { "maxDuration": 300 }
  },
  "rewrites": [
    { "source": "/v1/chat/completions", "has": [{ "type": "query", "key": "__go" }], "destination": "/api/index" },
    { "source": "/v1/chat/completions", "destination": "/api/chat-stream" },
    { "source": "/admin", "destination": "/admin/index.html" },
    { "source": "/(.*)", "destination": "/api/index" }
  ]
}

Requests to /v1/chat/completions route to the Node.js streamer, while the Go function handles health checks and admin endpoints. The Node stream proxy communicates with the Go "prepare" endpoint before relaying SSE data to the client.

Deploy and Verify

After configuring variables, click Deploy in the Vercel dashboard. The platform executes the build command from vercel.json, compiling both the WebUI assets and the Go binary.

Verify successful deployment by checking these endpoints:

1. https://<your-project>.vercel.app/healthz – Should return {"status":"ok"}.
2. /admin – Open the admin panel and log in using your DS2API_ADMIN_KEY.

If you see JSON responses and can access the admin interface, the deployment is functioning correctly.

Troubleshooting Common Issues

Symptom	Likely Cause	Solution
Go build fails (Error: Command failed: go build …)	Incorrect custom Go build flags in Vercel settings.	Clear custom flags or set -ldflags="-s -w" as a single argument.
"No Output Directory named 'public' found"	Vercel project settings override the output directory.	Ensure the output directory is set to static (or cleared to use the default from vercel.json).
"Authentication Required" HTML response	Vercel Deployment Protection is blocking API calls.	Disable protection for the environment or provide the DS2API_VERCEL_PROTECTION_BYPASS header/secret.
Internal package import error (use of internal package … not allowed)	Direct import of an internal Go package outside the allowed path.	Verify the code path uses the public bridge (api/index.go → ds2api/app) rather than internal packages.

Summary

• Fork required: You must fork CJackHwang/ds2api to your GitHub account before importing into Vercel.
• Key configuration: Set DS2API_ADMIN_KEY as a minimum; optionally provide DS2API_CONFIG_JSON as Base64 for pre-configuration.
• Hybrid architecture: Vercel runs Go code (api/index.go) for the API core and Node.js (api/chat-stream.js) for SSE streaming, orchestrated by vercel.json.
• Build output: The build command generates static assets in the static directory, not public.
• Verification: Check /healthz for status and /admin for the configuration interface.

Frequently Asked Questions

Can I deploy DS2API without setting DS2API_CONFIG_JSON initially?

Yes. If you omit DS2API_CONFIG_JSON, DS2API starts with an empty configuration. You can then upload a configuration JSON file through the admin UI at /admin and use the Vercel Sync feature to persist it back to your environment variables automatically.

Why does DS2API use two different runtimes on Vercel?

DS2API uses Go (api/index.go) for the core API logic because of its performance and concurrency handling, while using Node.js (api/chat-stream.js) specifically to handle Server-Sent Events (SSE) streaming. Vercel's streaming support works differently across runtimes, and this hybrid approach ensures reliable real-time data delivery through the Node wrapper while maintaining the Go backend's efficiency.

How do I fix "Authentication Required" errors when calling the API?

This error indicates that Vercel Deployment Protection is enabled and blocking your API requests. You must either disable Deployment Protection in your Vercel project settings for the specific environment, or configure DS2API_VERCEL_PROTECTION_BYPASS with a bypass secret and include it in your request headers.

What is the purpose of the VERCEL_TOKEN and related variables?

These variables (VERCEL_TOKEN, VERCEL_PROJECT_ID, VERCEL_TEAM_ID) enable the Vercel Sync feature in the admin UI. When configured, DS2API can automatically write configuration changes back to your Vercel environment variables via the Vercel API, eliminating the need to manually update Base64 strings in the dashboard after making changes through the web interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}