EN cPanel and Passenger

cPanel and Passenger setup

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

The Passenger path bridges ASGI to WSGI using a2wsgi for conventional HTTP APIs. Persistent WebSockets and Editor audio/video signaling require native ASGI.

Setup sequence

1. Place official server source in a private application directory, preferably outside public_html.
2. Create a supported Python environment with cPanel's Python application tool.
3. In that environment, run python -m pip install . or the repository's documented dependency installation.
4. Add your application under app/; use forge init --production for a new deployment.
5. Configure database URLs and actual host/proxy/IP settings.
6. Run forge validate, forge doctor --production and forge migrate.
7. Set the startup file to passenger_wsgi.py and the callable to application.
8. Restart through the panel, then test /health, /ready and a real project endpoint.

The provider's app root and working directory matter. Relative SQLite/data/env paths resolving to the wrong directory can cause missing files or an empty application list. Confirm provider-supported directives; one .htaccess is not universal across cPanel installations.

Private file placement

Do not expose .env, SQL files, databases, media roots or Editor attachments through direct web downloads. Avoid static-serving rules that expose arbitrary private files. Use the application's authorized download endpoints.

deploy/cpanel/.htaccess.example is a template. Replace account-path placeholders with real locations. Python versions, Passenger restart methods, egress, RAM and worker limits depend on the hosting provider.

Editor access

HTTPS JSON control-plane endpoints can work through the bridge. Restrict management to the intended private/VPN/IP policy. Disable setup and remove EDITOR_TOKEN after creating the founder.

Calls need a separate ASGI management deployment or provider-supported ASGI process and WebSocket proxy. A successful WSGI login does not establish that calls work. Confirm buffering, timeouts and long-response limits for SSE as well.

Common failures

Symptom	Check
Import error	Dependencies installed in cPanel's selected Python environment
500 on first request	Lifespan, DB connectivity, writable data directory
Healthy process but no project	App root, valid configuration, /ready
403	Actual proxy peer, Host, IP and HTTPS trust
Upload interrupted early	LiteSpeed/Apache/Passenger and Forge body limits
WebSocket/call fails	WSGI transport limitation; native ASGI required

Remove connection strings and tokens before sharing logs. Do not globally disable authentication or HTTPS checks to work around production errors.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/docs/cPanelGuide.md
• main/passenger_wsgi.py
• main/framework/wsgi.py
• main/deploy/cpanel/.htaccess.example

---

English home · All English pages · Version maintenance