How to install Webfaze

Before you start

• A licence and the download. Choose a plan on the pricing page. Your WFZ- licence key is then in Account, Licences, and the software is in Account, Downloads: the deploy package (a zip with webfaze.cjs, the start file app.js, package.json, a Dockerfile, a compose file, a systemd unit, a Caddyfile, an nginx example and a diagnostic, doctor.js).
• Node.js 22.15 or newer. Extensions need 22.15; Node.js 24 works too. Choose it in your hosting panel or install it on your server.
• A database. MySQL 5.7+ or MariaDB 10.2+: set DB_HOST, DB_NAME, DB_USER and DB_PASSWORD (or one DATABASE_URL). Or leave them all unset and Webfaze uses SQLite, a single file in its data folder with no setup. Either way Webfaze creates its own tables on first start; there is no SQL file to import.
• A domain pointed at your hosting, and outbound HTTPS from the server to webfaze.com about once a month for the licence check.

PHP-only shared hosting with no Node.js option can’t run Webfaze.

Option A: Hostinger or cPanel (Node.js app)

On Hostinger, Node.js apps need a Business or Cloud plan (hPanel, Websites, Node.js). On cPanel, look for Setup Node.js App.

1. Create a database (skip this for SQLite). In cPanel, MySQL Databases: create a database and a user, and add the user to the database with all privileges. In hPanel, Databases. Note the full names: hosting panels add a prefix such as youruser_ to both.
2. Upload the deploy package to a folder outside public_html, for example /home/youruser/webfaze, and extract it there. Outside the web root, your database and secrets can never be served by accident.
3. Create the Node.js app with these values:

   Node.js version

   22.15 or higher

   Application mode

   Production

   Application root

   webfaze

   Startup file

   app.js (not webfaze.cjs)

4. Add the environment variables. For MySQL:

   DB_HOST      localhost
   DB_NAME      youruser_webfaze
   DB_USER      youruser_wf
   DB_PASSWORD  your-database-password

   On cPanel also set WEBFAZE_DATA_DIR to /home/YOURUSER/webfaze/data. On Hostinger leave it unset: Webfaze keeps its data in domains/<your site>/webfaze-data, next to the app, where a redeploy can’t delete it. Don’t set PORT or WEBFAZE_HOST: the panel handles them, and overriding them causes a 503.
5. Start the app (Restart in the panel) and finish setup in one of two ways:
   • Open the app’s log. It shows a setup link ending in /install?t=…. Open it on your domain within 30 minutes and fill in the setup screens.
   • Or set WEBFAZE_DOMAIN, WEBFAZE_SITE_NAME, WEBFAZE_ADMIN_EMAIL and WEBFAZE_ADMIN_PASSWORD (at least 12 characters) before starting. Webfaze installs itself and you sign in at /admin. Delete WEBFAZE_ADMIN_PASSWORD from the panel afterwards.
6. Enter your licence key in the Console under Settings, Licence.

Seeing a 503? Read the app’s log in the panel first. If it doesn’t say enough, set the startup file to doctor.js, restart, read the log, then set it back to app.js. The most common cause is a database name or user typed without the panel’s prefix.

Option B: a VPS (systemd with Caddy or nginx)

Any Linux server with Node.js 22.15 or newer installed. This is the best-performing option.

1. Copy the deploy package to the server:

   scp -r ./* root@your-server:/opt/webfaze/

2. Create a locked-down user, so the app can write your content but not its own code:

   ssh root@your-server
   adduser --system --group --home /opt/webfaze webfaze
   chown -R root:root /opt/webfaze
   mkdir -p /opt/webfaze/data
   chown -R webfaze:webfaze /opt/webfaze/data
   chmod 750 /opt/webfaze/data

3. Run it as a service with the included unit. It listens on 127.0.0.1:8080. To use MySQL, add the DB_* variables to webfaze.service as Environment= lines first; without them Webfaze uses SQLite.

   cp /opt/webfaze/webfaze.service /etc/systemd/system/
   systemctl daemon-reload
   systemctl enable --now webfaze
   journalctl -u webfaze -n 20

   The log prints your setup link.
4. Add your domain and HTTPS. With Caddy, which gets and renews the certificate for you:

   apt install -y caddy
   cp /opt/webfaze/Caddyfile /etc/caddy/Caddyfile
   nano /etc/caddy/Caddyfile     # replace example.com with your domain
   systemctl reload caddy

   Prefer nginx? Start from nginx.conf.example in the package; it expects a Let’s Encrypt certificate. Point your domain’s A record at the server.
5. Finish setup at https://yourdomain.com/install?t=… with the token from the log, then enter your licence key under Settings, Licence.

The included service file stops Webfaze from changing its own webfaze.cjs, which is safer but means updates are installed by replacing the file and restarting. The file explains the one line to change if you want one-click updates from the Console.

Option C: Docker

1. Start it from the extracted deploy package, which includes a Dockerfile and docker-compose.yml:

   docker compose up -d
   docker compose logs | grep install

2. Open the setup link from the log. The app listens on port 8080; put Caddy or nginx in front for your domain and HTTPS, as on a VPS.
3. Enter your licence key under Settings, Licence.

Your content, uploads and secrets live in ./data on the host, so rebuilding or replacing the container leaves them untouched. For MySQL, add the DB_* variables to the service’s environment in docker-compose.yml.

On Railway, Render, Coolify or Fly, connect the package as an app, set WEBFAZE_DATA_DIR=/data and attach a persistent volume at /data. Without a persistent volume your content is erased on every redeploy.

After installing