Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tutosrive/factus_challenge/llms.txt
Use this file to discover all available pages before exploring further.
The reference deployment for Factus Challenge uses three cloud services working together: Koyeb hosts the Node.js + Express backend (bc-v1/), Render serves the static vanilla-JS frontend (fr-v1/), and Azure Database for PostgreSQL provides the persistent data store. Each service is independent — you can swap any one of them for an alternative without changing the others, as long as the environment variables and the backend URL in fr-v1/resources/assets/config.json are updated accordingly.
Backend (Koyeb)
Frontend (Render)
Database (Azure)
Koyeb is a serverless platform for containerised and Git-based workloads. It offers zero-cold-start Node.js hosting, automatic HTTPS, and a first-class environment variable panel — making it a good fit for a long-running Express server that must hold an OAuth token in memory between requests.Create a new Koyeb service
In the Koyeb dashboard, choose Create Service → Web Service and connect your GitHub repository. When prompted for the source directory, set it to bc-v1/.
Configure build and run commands
| Setting | Value |
|---|
| Build command | npm install |
| Run command | npm start |
npm start executes node ./src/main.js as defined in bc-v1/package.json.Add environment variables
In the Environment Variables section of the Koyeb service settings, add every variable listed in the Environment reference. The minimum required set is:url_api
client_id
client_secret
email
password
DB_USER
DB_HOST
DB_NAME
DB_PASSWORD
DB_SSL
client_secret, password, and DB_PASSWORD as secret so Koyeb masks them in the dashboard. Deploy
Click Deploy. Koyeb builds the service, installs dependencies with npm install, and starts the Express server. Once the health check passes you will see a public HTTPS URL in the format https://your-service-name.koyeb.app. Save this URL — you need it when configuring the frontend.
Koyeb runs production workloads as plain node processes, not via node --env-file .env. Do not rely on a .env file in production — use Koyeb’s built-in environment variable panel exclusively. The --env-file flag is only used by the dev, test, fact, and token npm scripts for local development.
Render can serve static sites directly from a GitHub branch with zero build configuration. Because fr-v1/ is a plain HTML/CSS/JS project with no bundler, there is nothing to compile — Render simply publishes the directory as-is.Create a new Render Static Site
In the Render dashboard, choose New → Static Site and connect your GitHub repository. Set the Root Directory to fr-v1/.
Leave the build command blank
The frontend has no build step. Leave Build Command empty (or set it to a no-op such as echo ok). Set Publish Directory to . (the root of fr-v1/, since you already set the root directory above).
Point the frontend at your Koyeb backend
After your Koyeb backend is live, copy its public HTTPS URL (e.g. https://your-service-name.koyeb.app) and update the frontend config file:fr-v1/resources/assets/config.json
{
"url": "https://your-service-name.koyeb.app"
}
Redeploy the Render site
Trigger a manual redeploy from the Render dashboard (or let the auto-deploy on push handle it). Once the deploy finishes, the frontend will reach the live backend.
The backend uses pg.Pool (src/database.js) to connect to a PostgreSQL instance. The reference deployment targets Azure Database for PostgreSQL - Flexible Server, which enforces SSL and provides a managed, scalable database with automatic backups.Create an Azure Database for PostgreSQL - Flexible Server
In the Azure Portal, navigate to Create a resource → Databases → Azure Database for PostgreSQL and select Flexible Server. Choose a region close to your Koyeb deployment region to minimise latency.
Note connection details
After provisioning, record the following values — you will need them as environment variables in Koyeb:| Variable | Where to find it |
|---|
DB_HOST | Server FQDN, e.g. your-server.postgres.database.azure.com |
DB_NAME | Database name you created |
DB_USER | Admin username set during provisioning |
DB_PASSWORD | Admin password set during provisioning |
Enable SSL enforcement
In the Server Parameters blade, ensure require_secure_transport is set to ON. Then set DB_SSL=true in your Koyeb environment variables so that pg.Pool opens TLS connections.
Whitelist Koyeb egress IPs
In the Azure Networking blade for your PostgreSQL server, add firewall rules to allow inbound connections from Koyeb’s published egress IP ranges. Alternatively, enable Allow access to Azure services if both services are in the same Azure region.
Run schema migrations
Connect to the database using psql or your preferred client and run your migration scripts to create the tables required by the application (clients, products, and any configuration tables).
Set DB_SSL=true in Koyeb
Confirm that DB_SSL=true is present in your Koyeb service’s environment variable panel. The pg.Pool in src/database.js reads process.env.DB_SSL directly as the ssl option — without this, connections to Azure will be rejected.
Alternative Hosting Options
The three services above are the reference deployment, but the application has no hard dependency on any of them. Any hosting that can run Node.js 22 and expose environment variables will work.
| Layer | Reference | Alternatives |
|---|
| Backend | Koyeb | Railway, Fly.io, Heroku, any VPS with Node.js 22+ |
| Frontend | Render (Static Site) | Vercel, Netlify, GitHub Pages, Cloudflare Pages |
| Database | Azure Database for PostgreSQL | Supabase, Neon, Railway PostgreSQL, self-hosted |
For local development, spin up a PostgreSQL instance with Docker so you don’t
need a cloud database at all:docker run \
--name factus-pg \
-e POSTGRES_PASSWORD=yourpass \
-e POSTGRES_USER=youruser \
-e POSTGRES_DB=factus \
-p 5432:5432 \
postgres:16
DB_HOST=localhost, DB_SSL=false (or omit DB_SSL) in your local
.env file and start the backend with npm run dev. 
