Manual setup and deployment

Put the store on a server: build, run with a process manager, put HTTPS in front, back up the database.

Souq is a standard Next.js application. Any host that runs Node.js works: a VPS, a dedicated server or a platform with a persistent disk. Below is the setup for a Linux VPS, which is the most common choice in Oman.

1. Copy the project and install

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

Edit .env for production:

  • SITE_URL = your real address with https:// (payment return links and the sitemap use it).
  • AUTH_SECRET = a new random value (never the one from your computer).
  • OWNER_EMAIL, OWNER_PASSWORD = the first owner. Change the password from the dashboard after the first sign-in.
  • DEMO_HINT="0" and SEED_DEMO_SHOPPER="0".

2. Database

With SQLite (fine for a single server and thousands of orders a month):

npm run setup

To start with an empty catalogue instead of the sample store, run npx prisma generate && npx prisma db push, then delete the sample products from the dashboard, or edit prisma/catalog-data.mjs before seeding.

For PostgreSQL, see Requirements.

3. Build and run

npm run build
npm start          # listens on port 3302

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

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

4. HTTPS in front

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

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

Then get a certificate (for example with Certbot). The sign-in cookies are marked Secure automatically when SITE_URL starts with https://.

X-Forwarded-For matters: the rate limits on sign-in, checkout and the contact form count requests per visitor IP.

5. Uploaded images

Images uploaded from the dashboard are saved in public/uploads/. Keep that folder when you deploy a new version (it is in .gitignore), and include it in backups. Files uploaded after the last build are served through /api/media, so they work without a rebuild.

6. Backups

Back up two things every day:

  • the database: prisma/souq.db (copy it while the server runs with sqlite3 prisma/souq.db ".backup souq-$(date +%F).db"), or your PostgreSQL dump;
  • public/uploads/.

7. Updating

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

prisma db push warns before any change that would lose data. Read the warning; never add --force-reset on a live store.

Several server instances

The rate limiter keeps its counters in memory, per process. If you run more than one instance behind a load balancer, move the counters to a shared store (Redis) in src/lib/api.ts, and use PostgreSQL instead of SQLite.