This guide explains how to deploy ZenServer on Val Town, which has specific restrictions on filesystem access.

Val Town doesn't allow filesystem operations for security reasons. This means:

• No reading .env files
• No writing log files
• No reading JSON files from disk

We've created Val Town-compatible versions of the core modules:

1. main-valtown.ts - Entry point for Val Town
2. src/config/env-loader-valtown.ts - Environment loader that skips file operations
3. src/utils/logger-valtown.ts - Console-only logger (no file writes)
4. src/utils/openApiLoader-valtown.ts - Uses embedded OpenAPI spec
5. src/utils/embeddedOpenApiSpec.ts - OpenAPI spec as JavaScript object
6. src/gateway/apiGateway-valtown.ts - API Gateway using Val Town modules

In your Val Town settings, set these environment variables:

PAYMENT_USERNAME=your_zenpay_username
PAYMENT_PASSWORD=your_zenpay_password
TURNSTILE_SECRET_KEY=your_cloudflare_turnstile_key
ALLOWED_ORIGINS=https://yourdomain.com,https://anotherdomain.com
LOG_LEVEL=INFO
WEBHOOK_SECRET=your_webhook_secret
SESSION_SECRET=your_session_secret
APP_ENV=prod
VALTOWN_TOKEN=your_valtown_token
ADMIN_API_KEY=your_admin_api_key

Create a new HTTP Val and use this code:

// Import the Val Town compatible version
import zenServer from "https://esm.town/v/yourusername/ZenServer-valtown";

// Export the default handler
export default zenServer;

Or if you're copying the entire codebase:

// Use the Val Town compatible main file
import "./main-valtown.ts";

If copying files to Val Town, update these imports in existing files:

// In files that import env-loader
import { loadDevEnvironment } from "./src/config/env-loader-valtown.ts";

// In files that import logger
import { logger, logInfo, logError } from "./src/utils/logger-valtown.ts";

// In files that import openApiLoader
import { createOpenAPILoader } from "./src/utils/openApiLoader-valtown.ts";

// In main entry point
import app from "./src/gateway/apiGateway-valtown.ts";

After deploying, test these endpoints:

• GET / - Should return "ZenServer is running on Val Town!"
• GET /health - Should return "OK"
• GET /openapi.json - Should return the OpenAPI specification
• GET /api/v1/tours - Should return the list of tours

1. No File System Access: All file operations are removed
2. Console Logging Only: No log files are created
3. Embedded OpenAPI Spec: The spec is included as a JavaScript object
4. Environment Variables: Must be set via Val Town's UI, not .env files

1. "NotCapable" Errors: These indicate filesystem access attempts. Use the Val Town compatible versions.

2. Missing Environment Variables: Set all required variables in Val Town's environment settings.

3. Import Errors: Ensure you're using the -valtown versions of modules.

To enable debug mode on Val Town:

1. Set DEBUG_MODE=true in environment variables
2. Debug output will appear in Val Town's console logs

1. Rate Limiting: In-memory rate limiting resets when Val restarts
2. Session Storage: Sessions are temporary and reset on Val restart
3. Database: Ensure your SQLite database is properly configured for Val Town

For issues specific to Val Town deployment, check:

• Val Town documentation: https://docs.val.town
• ZenServer Val Town issues: [create an issue with "valtown" tag]