Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/edgar2420/QrPermision/llms.txt

Use this file to discover all available pages before exploring further.

PermisosQR ships with two shell scripts — setup.sh and start.sh — that automate the entire Ubuntu deployment process. setup.sh provisions every dependency from scratch (Node.js, PostgreSQL, the database, and an SSL certificate), while start.sh launches both the backend and frontend in a single command with a clean URL summary. Together they take a bare Ubuntu machine from zero to a running, SSL-enabled instance in a few minutes.
The self-signed SSL certificate generated by setup.sh will trigger a browser security warning on first visit. This is expected behaviour for local network deployments. Click Advanced → Proceed (Chrome) or Accept the Risk (Firefox) to continue. For a public-facing deployment, replace the self-signed certificate with one issued by a trusted CA (e.g. Let’s Encrypt).
1

Clone the repository and run setup.sh

git clone https://github.com/edgar2420/QrPermision.git
cd QrPermision
chmod +x setup.sh
./setup.sh
setup.sh performs the following steps automatically:
  1. Node.js 20 — Checks whether Node is already installed; if not, adds the NodeSource repository and installs nodejs via apt.
  2. PostgreSQL — Installs postgresql and postgresql-contrib if psql is not found, then starts and enables the service so it survives reboots.
  3. Database — Sets the postgres user password to root, creates the permisosqr database, and applies database/schema.sql to build the three core tables (users, qr_codes, permissions). Note: setup.sh and the db:migrate/db:seed npm scripts both reference the database/ path, but the SQL files actually live in the base/ directory of the repository. When running SQL manually outside of these scripts, use base/schema.sql and base/seed.sql.
  4. Backend dependencies — Creates .env from .env.example if it does not already exist, then runs npm install inside backend/.
  5. Frontend + SSL — Runs npm install and npm run build inside frontend/, then generates a 10-year self-signed certificate (cert.pem / key.pem) scoped to the machine’s local IP address using openssl.
2

Start all services with start.sh

chmod +x start.sh
./start.sh
start.sh does four things:
  • Generates the SSL certificate pair if it is missing (using the same openssl command as setup.sh).
  • Spawns node backend/src/index.js in the background on port 4000.
  • Spawns npm run preview --prefix frontend in the background on port 3000, serving the pre-built Vite output over HTTPS.
  • Detects the machine’s local IP via hostname -I and prints the direct access URLs to the terminal.
Press Ctrl+C to stop both processes gracefully; the trap handler kills both PIDs before exiting.
3

Access the application

Once start.sh reports that both processes are running, open the following URLs:
SurfaceURL
Backend APIhttp://localhost:4000
Health checkhttp://localhost:4000/api/health
Frontend (local)https://localhost:3000
Frontend (network)https://<local-ip>:3000
The network URL (with your machine’s LAN IP) is the one to share with mobile devices on the same Wi-Fi network for QR scanning. Accept the self-signed certificate warning on first visit, and the app will behave like a normal HTTPS site from that point on.

​
Manual Setup

If you prefer to run each service independently — or if you are deploying to a server where setup.sh is not appropriate — follow the steps below. 
cd backend
npm install
node src/index.js
The server reads all configuration from .env. Make sure the file exists and contains valid PostgreSQL credentials before starting. The process listens on 0.0.0.0:4000, so it is reachable from any network interface.For long-running deployments, consider wrapping the process with a process manager such as pm2 or a systemd service unit to handle restarts on failure.

​
Port Reference

ServiceDefault Port
Backend API4000
Frontend3000
PostgreSQL5432
All three defaults can be changed: the backend port is controlled by PORT in .env; the frontend preview port can be overridden with --port in the Vite config; PostgreSQL’s port is set in DB_PORT in .env.
Production reminder: Before exposing PermisosQR to the internet, open backend/.env and replace the placeholder JWT_SECRET value with a securely generated random string (at least 32 characters). You can generate one with openssl rand -hex 32. Leaving the default value in place means any attacker who reads the source code can sign arbitrary tokens.

Build docs developers (and LLMs) love

Get started for freeTalk to us