Home

This documentation is split into focused pages so installation, administration and troubleshooting information can be maintained independently.

Start here

• Requirements — software, hosting, database, and environment requirements.
• Install on N0C — PlanetHoster/N0C/Passenger deployment.
• Install on cPanel — generic cPanel Node.js deployment.
• Install on a Home Server — self-hosting behind a reverse proxy.
• Admin Dashboard — what each CMS module does.
• SEO and Meta Tags — SEO fields, social previews and custom meta tags.
• Troubleshooting — common errors and known fixes.
• Updates and CI — versioning, updater detection and GitHub Actions checks.
• License and Credits — original foundation, derivative authorship, contributors, third-party software and redistribution guidance.

Project stack

The application is a Next.js portfolio/CMS with Prisma and PostgreSQL, an authenticated Admin area, Blog, Projects, Gallery, Media Library, SEO settings, comments, site modes, and an application updater.

Production deployments should always be treated as a Node.js application. Do not deploy it as a static HTML-only website unless the application is intentionally converted to static output.

Recommended documentation order

For a new installation:

1. Read Requirements.
2. Choose the deployment guide for the hosting environment.
3. Configure the production environment variables.
4. Deploy Prisma migrations.
5. Build the application.
6. Start or restart the Node application.
7. Verify the public site, Admin, and database-backed routes.
8. Read Troubleshooting before making hosting-specific workarounds.

For content editors, start with Admin Dashboard and SEO and Meta Tags.

Before redistributing or publishing a fork, read License and Credits and preserve the required notices.

Important production rule

Never commit production secrets such as DATABASE_URL, AUTH_SECRET, storage credentials or private API keys to GitHub.

Requirements

This page describes the practical requirements for running the Portfolio application.

Runtime

Recommended production baseline:

• Node.js 22.x, matching the current CI environment.
• npm 10.x or compatible.
• PostgreSQL 14+; PostgreSQL 16 is used by CI.
• A hosting environment that can run a persistent Node.js application.
• HTTPS in production.
• Git for normal deployment/update workflows.

Shared hosting must explicitly support Node.js applications. PHP-only hosting is not sufficient.

Application stack

The project uses:

• Next.js
• React
• Prisma ORM
• PostgreSQL
• authenticated Admin access
• server-side routes/actions
• Media Library storage
• GitHub-based release/update workflow

Because the application contains server routes and database access, it is not a simple static site.

Production environment variables

The exact set depends on enabled integrations, but production should at minimum verify:

NODE_ENV=production
NEXT_PUBLIC_SITE_URL=https://your-domain.example
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DATABASE?schema=public&connection_limit=1&pool_timeout=20
AUTH_SECRET=replace-with-a-long-random-secret

Additional variables may be required for external storage, AI services, email or other integrations enabled in the installation.

DATABASE_URL

For shared hosting/Passenger environments, this project has previously required conservative Prisma connection settings:

connection_limit=1&pool_timeout=20

This reduces the chance that several Passenger Node processes exhaust a small PostgreSQL connection allowance.

Do not copy these numbers blindly to a large dedicated server; tune them according to the database and process limits.

Server resources

A practical minimum for a small deployment is approximately:

• 1–2 CPU cores
• 1 GB RAM minimum; 2 GB+ is preferable for builds
• sufficient temporary disk space for node_modules and .next
• persistent storage for uploaded files if local storage is used

Building Next.js usually needs more memory than simply running an already-built application. Shared hosting with aggressive memory limits may fail during build even when runtime traffic would be light.

Database

PostgreSQL must be reachable from the Node runtime, not merely from an interactive SSH shell.

Before deployment verify:

npx prisma validate
npx prisma generate
npx prisma migrate status

Production schema changes should be applied with:

npx prisma migrate deploy

Do not use prisma migrate dev in production.

Reverse proxy / application server

Supported patterns include:

• Passenger-managed Node application on N0C/PlanetHoster.
• cPanel Application Manager / Setup Node.js App.
• Direct Node.js process behind Nginx, Apache or Caddy.
• A process manager such as systemd or PM2 on a self-managed server.

The reverse proxy must forward requests to the Node application instead of rewriting application routes to unrelated PHP/static handlers.

Domain and TLS

Production should use:

• a real domain or subdomain;
• HTTPS;
• correct NEXT_PUBLIC_SITE_URL;
• proxy headers that preserve the original host/protocol where required.

Wrong public-site URLs can lead to incorrect canonical, Open Graph, X/Twitter and authentication URLs.

Build checks before production

A release should pass:

npm run typecheck
npm run lint
npm run build

On the N0C environment, use the repository compatibility build when native SWC is unavailable:

npm run build:n0c

CI should also pass Prisma migration checks and visual smoke tests.

Browser support

The public site targets modern evergreen browsers. The Admin area should be used with a current Chrome, Edge, Firefox or Safari release.

Mobile layout should be checked separately because viewport behavior (dvh, browser bars and safe areas) differs from desktop.