Manual setup and deployment

Put the academy on a server: build, run with a process manager, HTTPS in front, uploads and backups.

Maarifa is a standard Next.js application. Any host that runs Node.js with a persistent disk works: a VPS, a dedicated server or a container platform. Below is the setup for a Linux VPS.

1. Copy the project and install

git clone <your repository> /var/www/maarifa
cd /var/www/maarifa
npm ci
cp .env.example .env

Edit .env for production:

  • SITE_URL = your real address with https://. Payment return links, certificate verification links and the sitemap use it.
  • AUTH_SECRET = a new random value.
  • ADMIN_EMAIL, ADMIN_PASSWORD = the first admin. Change the password from Dashboard > Admins after the first sign-in.
  • DEMO_HINT="0", SEED_DEMO_STUDENT="0" and DEMO_INSTRUCTOR_PASSWORD="".

2. Database

With SQLite (fine for one server and thousands of learners):

npm run setup

For PostgreSQL see Requirements.

3. Build and run

npm run build
npm start          # listens on port 3305

Keep it running with a process manager, for example PM2:

npm install -g pm2
pm2 start npm --name maarifa -- start
pm2 save && pm2 startup

4. HTTPS in front

Put a web server in front that handles HTTPS and forwards to port 3305. With Nginx:

server {
  server_name learn.example.om;
  client_max_body_size 6m;            # image uploads are up to 5 MB
  location / {
    proxy_pass http://127.0.0.1:3305;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Get a certificate (for example with Certbot). Sign-in cookies are marked Secure automatically when SITE_URL starts with https://. Keep X-Forwarded-For: the limits on sign-in, sign-up, checkout and quiz attempts count requests per visitor.

5. Uploaded images and videos

Images uploaded from the dashboard (course covers, instructor portraits, blog covers) are saved in public/uploads/. Keep that folder between deployments and include it in backups. Files uploaded after the last build are served through /api/media, so they work without rebuilding.

Lesson videos are not uploaded to the server: host them on YouTube (unlisted), Vimeo, or any storage that serves MP4 files over https, and paste the link in the lesson.

6. Backups

Every day, back up:

  • the database: prisma/maarifa.db (while running: sqlite3 prisma/maarifa.db ".backup maarifa-$(date +%F).db"), or your PostgreSQL dump;
  • public/uploads/;
  • your .env (store it somewhere private).

Certificates are rows in the database: losing the database means verification links stop working, so test restoring a backup once.

7. Updating

git pull
npm ci
npx prisma db push      # applies new columns, keeps your data
npm run build
pm2 restart maarifa

prisma db push refuses changes that would delete data and tells you why. Read its message before continuing.

Docker (optional)

Any Node 22 image works: copy the project, run npm ci && npm run build, start with npm start, and mount prisma/ (or point DATABASE_URL to PostgreSQL) and public/uploads/ as volumes.