Koapanel
IT Try it free
All manual sections

DocumentationNode.js and Python applications

Node.js and Python applications

A site can be a Node.js or Python application instead of PHP: Express, Next.js, NestJS, Django, Flask, FastAPI and the like. It is set up on the site page, Node.js / Python tab.

How it works

  • The application runs as a system service with the site user: the same permissions as the site's files, no access to other sites. The service has a memory and CPU limit (512 MB and one core by default) and restarts by itself if it stops with an error.
  • nginx stays in front: HTTPS certificate, HTTP/2, WebSocket. It passes every request to the application, which must listen on 127.0.0.1 on the port given in the PORT variable (the panel chooses and sets it).
  • The versions are installed by the panel when needed: Node.js from the official nodejs.org packages (checked against their SHA-256), Python with uv; each Python application has its own .venv virtual environment.

Creating it

  1. Choose language and version, the folder (inside the site home, outside public_html; app by default) and the start command. Empty means npm start (or node server.js) for Node.js and python app.py for Python. Examples: gunicorn -b 127.0.0.1:$PORT project.wsgi, uvicorn main:app --host 127.0.0.1 --port $PORT, node dist/main.js.
  2. Add the environment variables (one per line, NAME=value): PORT, HOST and PATH are set by the panel, NODE_ENV is production unless you change it.
  3. Press Start the application. If the folder is empty the panel writes a small example that answers right away; then upload your files with the file manager or SFTP, or use the Git deploy.

Before starting, the panel installs the dependencies (npm ci or npm install when there is a package.json; uv pip install -r requirements.txt or the pyproject.toml for Python) and runs the build command, if any.

Deploy from Git

Enter the repository (a public https://… one or git@github.com:company/app.git) and the branch. For a private repository press Show the deploy key and add it to the repository as a read-only key (GitHub: Settings › Deploy keys; GitLab: Settings › Repository › Deploy keys).

Deploy fetches the latest version of the branch, installs the dependencies, runs the build, restarts the service and runs the health check: if the application does not answer (error 500 or no answer on the given path, / by default), the deploy is reported as failed and you find the reason in the log.

Managing it

  • Restart, Stop, Start, Check (immediate health check).
  • Log: the last lines written by the application (what it prints on standard output and error).
  • Remove the application stops the service and the site is served by PHP again; the files in the folder stay.
  • Site backups include the application folder (it is in the site home); its database, if it uses MySQL or PostgreSQL, is in the backups too.

Good to know

  • On a site with WordPress or with an application of Install apps a Node.js or Python application cannot be turned on: use another site (for example a subdomain such as api.example.com).
  • The service can write only in the site home; /tmp is private to each application.