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 withhttps://(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"andSEED_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 withsqlite3 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.