Storify Setup & Installation

Storify is a complete ecommerce platform: storefront, admin dashboard, vendor marketplace, point of sale, payments, shipping and AI tools. It is built with Next.js 16, React 19, Tailwind CSS 4, MongoDB and Better Auth. This documentation takes you from the zip you downloaded to a live store, and then explains each feature's settings.

You can run Storify on your own computer to try it, or put it online with Dokploy, Vercel or a plain VPS. Every path ends at the same five-step installer in your browser. Pick one path. Then prepare your accounts and values in Before You Install, and follow only your path's chapter.

This is the short local path for people who already have Node.js 24, pnpm and MongoDB. It gives you a private test store on your own computer, in roughly 15 minutes. If any of these tools are new to you, follow Set Up Your Computer instead: it covers the same steps in more detail.

1. 1

   Install the packages

   Open a terminal in the app folder and install the packages Storify needs. The first install downloads a lot and can take a few minutes.

   1. 1Windows: open the app folder in File Explorer, click the address bar, type cmd and press Enter.
   2. 2macOS or Linux: open Terminal, type cd and a space, drag the app folder into the window, and press Enter.
   3. 3Run the command below.

   bashCopy

   pnpm install

   An error that starts with ERR_PNPM_ usually means the wrong pnpm version, or hidden files (such as pnpm-workspace.yaml) that were lost while copying the folder. Set Up Your Computer shows how to fix both.

   Check: The output ends with a line that starts with Done in. Yellow WARN lines are normal. A line with ERR_PNPM is not.

2. 2

   Generate two secrets

   Storify needs two long random values: one protects sign-in (BETTER_AUTH_SECRET) and one protects the scheduled jobs (CRON_SECRET). Run the command below twice and copy each result.

   Windows, macOS and Linux

   bashCopy

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

   macOS / Linux alternative

   bashCopy

   openssl rand -hex 32

   Paste the printed value, never the command itself. Keep both values in a password manager.

   Check: Each run prints a different line of 64 characters: digits and the letters a to f.

3. 3

   Create the .env file

   The .env file holds your settings. Create it in the app folder, in the same terminal. Payment, email and storage keys come later; you do not need them now.

   1. 1Windows: run notepad .env. If Notepad asks whether to create a new file, click Yes.
   2. 2macOS: run touch .env, then open -e .env to open it in TextEdit.
   3. 3Linux: run nano .env. Save with Ctrl+O and Enter, close with Ctrl+X.
   4. 4Paste the block below. Replace both <…> placeholders, including the < and > signs, with your two secrets. Save the file.

   .env

   txtCopy

   MONGODB_URI=mongodb://localhost:27017/storify
   MONGODB_DB_NAME=storify
   BETTER_AUTH_SECRET=<the first 64-character secret>
   BETTER_AUTH_URL=http://localhost:3000
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   CRON_SECRET=<the second 64-character secret>

   Using MongoDB Atlas? Replace the first line with your Atlas connection string, with /storify before the ?, and allow your current IP address in Atlas. Keep MONGODB_DB_NAME=storify either way. See Database Setup.

   Check: dir .env (Windows) or ls -a .env (macOS and Linux) lists a file named exactly .env. Windows lists .env.txt instead? Rename it with ren .env.txt .env.

4. 4

   Start the app

   Start the development server and leave this terminal open while you use the store. Press Ctrl+C in it to stop the store. After you change .env, stop it and run pnpm dev again.

   bashCopy

   pnpm dev

   Want the full demo store (products, orders and demo logins) instead of the installer? Run pnpm db:seed before you start the app and before you open the site for the first time. Then sign in at http://localhost:3000/login with the logins it prints, and change their passwords. The seed locks the installer, so never run it on a live store's database. Details: Database Setup.

   Check: The terminal shows http://localhost:3000 next to Local:, then a line with Ready in.

5. 5

   Run the installer

   Open http://localhost:3000 in your browser. A new store sends you to /install. The first page can take a minute to appear. Work through the five screens; First Run & Installer explains each one.

   1. 1System check: the Node.js, MongoDB connection and Authentication secret rows must pass. Click Continue.
   2. 2Create your admin account: your name, email and a password of at least 8 characters. This account becomes the store's Owner.
   3. 3Store basics: store name, language and currency. Untick "Multi-vendor marketplace" if you run a single store.
   4. 4Where media is stored: enter your bucket details, or tick "Set storage up later".
   5. 5Choose your storefront template: keep the demo data box ticked for a sample catalog, then click Install.

   A row failed in the System check? Fix the value in .env, restart pnpm dev, then click "Check again".

   Check: You see "Your store is ready". Click "Go to sign in" and sign in with your new admin account; http://localhost:3000/admin opens the dashboard.

Storify is one Node.js app that keeps running, one MongoDB database and one storage bucket for uploads. This page lists the software versions and the machine size each path needs. Building the app takes much more memory than running the store, so the build decides how big a server must be.

Dokploy, Vercel, a VPS or your own computer: every path needs the same few things. Do them once here and write each value down in one private place. Your path chapter then tells you exactly where to paste them. A step that your path does not need says so.

1. 1

   Download and unzip the package

   The app folder is the folder you install. It contains hidden files (their names start with a dot). They must stay with it wherever you copy or upload it.

   1. 1Sign in at codecanyon.net, open your account menu (your user name, top right) and click Downloads.
   2. 2Find Storify, click Download and choose All files & documentation (the label may differ slightly). Save the zip file.
   3. 3From the same Download menu, also save the License certificate & purchase code. Support asks for your purchase code.
   4. 4Unzip the file. Windows: right-click it → Extract All… → Extract. macOS: double-click it. Linux: run unzip followed by the file name.
   5. 5If you find another zip file inside, unzip that one too. Open folders until you see the app folder: the one that contains package.json, vercel.json, .env.example and next.config.ts.
   6. 6Move the app folder to a place you will keep, for example C:\storify on Windows or a storify folder in your home folder on macOS. Do not use a folder that OneDrive, iCloud or Dropbox syncs: syncing thousands of small files slows everything down and can break the install.
   7. 7Show hidden files. Windows 11: File Explorer → View → Show → click Hidden items, and also File name extensions. Windows 10: View tab → tick Hidden items and File name extensions. macOS Finder: press Cmd+Shift+. (period).

   Keep every hidden file when you copy, zip or upload the folder: .env.example, .nvmrc, .pnpmfile.cjs, .gitignore and the .github folder. Keep pnpm-workspace.yaml and pnpm-lock.yaml too. Without .pnpmfile.cjs or pnpm-workspace.yaml the install stops with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH.

   Check: Inside the app folder you see package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .pnpmfile.cjs and .env.example. Files that start with a dot missing? Turn on hidden files (last item above) and look again. Still missing? Download the zip again, or contact support.

2. 2

   Create the MongoDB database

   MongoDB is the database that holds your products, orders and users. Most stores use MongoDB Atlas, a hosted MongoDB with a free tier. Dokploy users may run MongoDB inside Dokploy instead (Deploy with Dokploy), and local testers may run MongoDB on their own computer with Docker or MongoDB Community Server (Database Setup). If you choose one of those, skip this step and the next one.

   1. 1Sign up at MongoDB Atlas. Answer or skip the welcome questions.
   2. 2Create a cluster (Atlas's name for a database server) and choose the Free tier: 512 MB of data, no automatic backups. It is fine for testing and a first launch. For a busy live store, use a paid tier or scheduled backups.
   3. 3Choose the region closest to where the store will run: your server's location (Dokploy, VPS) or your customers (Vercel). Create the cluster. This takes a few minutes.
   4. 4Atlas now asks you to create a database user (it may suggest a name and password). Use a user name such as storify_app and a password with letters and digits only, then create the user. Save the password in your password manager now. If Atlas does not ask, open Security → Database & Network Access → Database Users → Add New Database User.
   5. 5Open Security → Database & Network Access → IP Access List tab → Add IP Address. This list says which computers may connect to the database.
   6. 6Enter the entry for your path from the list below, then click Save and Close. Testing locally and deploying later? Add both entries.

   Local (your computer)

   Your current IP address. Atlas may have added it already while you created the cluster. If not, click the Add Current IP Address button. If your home IP address changes later, add the new one.

   Dokploy or VPS

   Your server's public IP address, for example 203.0.113.10. Your VPS provider's dashboard shows it.

   Vercel

   0.0.0.0/0 (the Allow Access from Anywhere button). Vercel has no fixed IP address, so this is required.

   Atlas emails every project member an alert about a 0.0.0.0/0 entry. This is expected. The database is still protected by its user name and password. The Atlas labels may differ slightly from the ones here.

   Check: The IP Access List tab shows your entry, and the Database Users tab lists your user.

3. 3

   Build your MongoDB connection string

   The connection string tells Storify where the database is and how to sign in to it. Atlas gives you most of it. You add the password and the database name.

   1. 1In Atlas, open Clusters, click Connect on your cluster, then choose Drivers.
   2. 2Copy the connection string it shows and paste it into your notes.
   3. 3Replace <db_password> with your database user's password. Remove the < and > too. If you also see <db_username>, replace it with your user name.
   4. 4Make the part after .mongodb.net read /storify?. Atlas strings usually contain .mongodb.net/?: type storify between the / and the ?.

   User name

   Your database user, for example storify_app. Atlas usually fills it in.

   Password

   Replaces <db_password>. Change special characters as shown in the note below.

   Cluster address

   For example cluster0.xxxxx.mongodb.net. Keep it exactly as Atlas wrote it. Every cluster has its own.

   Database name

   storify. You add it yourself, between .mongodb.net/ and ?.

   Options

   ?retryWrites=true&w=majority. Keep these, and anything else Atlas added, such as &appName=Cluster0.

   The finished string looks like this

   txtCopy

   mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority

   Special characters in the password break the string. Replace them: @ → %40, : → %3A, / → %2F, # → %23, ? → %3F, % → %25. Or give the database user a password with letters and digits only.

   Check: Your string starts with mongodb+srv://, has no < or > left, and contains .mongodb.net/storify?. It ends like …/storify?retryWrites=true&w=majority (an extra &appName=Cluster0 is fine).

4. 4

   Generate your secrets

   Storify needs two long random values. One protects sign-in sessions. The other protects the background jobs. The command below makes them and works on Windows, macOS and Linux.

   1. 1Open a terminal (the window where you type commands). Windows: press Start, type cmd and press Enter. macOS: open Terminal from Applications → Utilities.
   2. 2Paste the first command below and press Enter. It prints one line of 64 characters.
   3. 3Copy that line into your notes as the value of BETTER_AUTH_SECRET.
   4. 4Run the command again. Save the new line as CRON_SECRET. The two values must be different.
   5. 5Later, if you connect chat channels, run it a third time for MESSAGING_ENCRYPTION_KEY (see "Write down your environment values" below).

   Windows, macOS and Linux (uses Node.js)

   bashCopy

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

   macOS and Linux only (alternative)

   bashCopy

   openssl rand -hex 32

   Save the line the command prints. Never save the command itself or a placeholder such as <64 characters>. If the terminal says node is not recognized or not found, install Node.js first: see Set Up Your Computer.

   Check: Each value is exactly 64 characters long and uses only the digits 0–9 and the letters a–f. The two values are different.

5. 5

   Decide your store address

   Two variables, BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL, will both hold this one address. Use https://, put no slash at the end, and write it exactly as people will type it. https://www.your-domain.com and https://your-domain.com are two different addresses, so pick one.

   Local (your computer)

   http://localhost:3000. This is the only address that uses http://.

   Vercel

   Start with https://<project-name>.vercel.app, using the project name you will type in Vercel. Vercel may add a suffix if the name is taken, so you check the real address after the first deploy. Later you move both variables to your own domain: Deploy to Vercel shows how.

   Dokploy or VPS

   The domain or subdomain you will point at your server, for example https://shop.your-domain.com.

   Sign-in works only on this exact address. Anywhere else it fails with 403 "Invalid origin": on the www version when you chose the address without www (or the other way round), on another Vercel address, or on http instead of https. If you change the address later, change both variables and rebuild. Your path chapter shows how.

   Check: You have one address written down. It starts with https:// (or is http://localhost:3000) and ends right after the domain name, with no / at the end.

6. 6

   Write down your environment values

   Environment variables are the settings Storify reads when it starts: each one is a NAME=value line. Put your production values into your private note in the format shown below. Your path chapter tells you where to paste them. A local install puts the same names in a .env file with http://localhost:3000 as the address: see Environment Variables.

   MONGODB_URI

   Your finished connection string from the step above, with the password already encoded. Dokploy users with a Dokploy MongoDB service get their string in Deploy with Dokploy.

   MONGODB_DB_NAME

   storify, the same name as in your connection string. Always set it. If it is missing and the connection string has no database name, the store quietly uses a database called test, and pnpm create-admin refuses to run.

   BETTER_AUTH_SECRET

   Your first secret. It protects sign-in sessions. Spell the name exactly like this: the installer checks only this name.

   BETTER_AUTH_URL

   Your store address.

   NEXT_PUBLIC_APP_URL

   The same address. It is built into the app when the app is built, so after changing it you must rebuild, not only restart.

   CRON_SECRET

   Your second secret. The background jobs send it to prove they may run. Without it every job is refused (error 401).

   Vercel adds

   ENABLE_EXPERIMENTAL_COREPACK=1. It makes Vercel install with exactly pnpm 10.24.0.

   Dokploy adds

   NIXPACKS_NODE_VERSION=24. It makes the Dokploy build use Node.js 24.

   Later: MESSAGING_ENCRYPTION_KEY

   Only when you connect WhatsApp, Messenger, Instagram or Telegram, or when vendors save their own carrier accounts. Use a third 64-character secret. Never change it afterwards, or the saved connections can no longer be read.

   Production values (Dokploy, Vercel, VPS)

   bashCopy

   MONGODB_URI=mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority
   MONGODB_DB_NAME=storify
   BETTER_AUTH_SECRET=<64 characters from the command above>
   BETTER_AUTH_URL=https://your-store-url
   NEXT_PUBLIC_APP_URL=https://your-store-url
   CRON_SECRET=<a different 64 characters>

   Do not paste the whole .env.example file into a hosting panel. Its placeholder values count as real: fake STORAGE_* keys make the installer skip the storage step, ADMIN_PASSWORD=change-me becomes the password pnpm create-admin gives, and CRON_SECRET=replace-with-… passes as a real secret. Enter only the variables you fill in yourself.

   Check: Your note has the six NAME=value lines (plus the extra line for Vercel or Dokploy). No < or > is left, there are no spaces around =, and both URL lines hold the same address.

7. 7

   Put the source in a private GitHub repository

   Vercel and Dokploy build your store from a GitHub repository (an online copy of the app folder). It must be private, because Storify is licensed source code. A local install skips this step; on a VPS it is optional. Do not use GitHub's upload page: it accepts at most 100 files at a time, and Storify has about 3,100.

   1. 1Install GitHub Desktop and sign in with your GitHub account.
   2. 2Click File → Add local repository and choose the app folder (the one with package.json).
   3. 3GitHub Desktop says the folder is not a Git repository. Click the "create a repository" link, leave the options as they are, and click Create repository. GitHub Desktop saves all files in a first commit (a saved version) by itself.
   4. 4Click Publish repository. Keep "Keep this code private" ticked, then click Publish repository.
   5. 5Prefer the command line instead of GitHub Desktop? You need Git. On github.com click + → New repository, name it storify, choose Private, add no README, .gitignore or license, and click Create repository.
   6. 6In a terminal, go to the app folder, for example cd C:\storify (Windows) or cd ~/storify (macOS). Run the commands below, with your GitHub user name in place of YOUR-USERNAME.

   Command line (instead of GitHub Desktop)

   bashCopy

   git init
   git add .
   git commit -m "Storify"
   git branch -M main
   git remote add origin https://github.com/YOUR-USERNAME/storify.git
   git push -u origin main

   First time using Git on the command line? If git commit says "Author identity unknown", run git config --global user.name "Your Name" and git config --global user.email "you@example.com", then commit again. On Windows, many lines like LF will be replaced by CRLF are harmless warnings. When git push asks you to sign in, approve it in the browser, or use a personal access token as the password.

   Check: On github.com the repository shows the Private label, lists package.json, vercel.json and .env.example at the top level (not inside a subfolder), and has no .env file. GitHub may also email you that a workflow named Deploy image failed. It runs on every push but is used only by Dokploy Path B (Deploy with Dokploy). If you do not use Path B, ignore it or turn it off: Actions tab → Deploy image → ⋯ → Disable workflow.

8. 8

   Create a storage bucket

   Product images and other uploads are not kept on your server. They live in a bucket: online file storage that works like Amazon S3 ("S3-compatible"). Cloudflare R2 is the usual choice. Other providers are in Storage & Media. The installer lets you tick "Set storage up later", but nothing can be uploaded until storage is set, so do it now or right after the install.

   1. 1In the Cloudflare dashboard, open R2 (under Storage & databases). The first time, Cloudflare asks you to add R2 to your account through a short checkout.
   2. 2Click Create bucket and name it, for example storify-media (lowercase letters, digits and hyphens).
   3. 3Open the bucket → Settings. Under Public Development URL, click Enable, type allow and confirm. Copy the public URL it shows, like https://pub-xxxx.r2.dev.
   4. 4Go back to the R2 overview page. Under Account Details, copy your Account ID, then click Manage next to API Tokens.
   5. 5Create an Account API token with the permission Object Read & Write, limited to your bucket. Copy the Access Key ID and the Secret Access Key. The secret is shown only once.
   6. 6Open the bucket → Settings → CORS Policy → Add CORS policy. On the JSON tab, paste the rule below, put your store address in place of https://your-store-url, and click Save. Testing locally too? Add "http://localhost:3000" as a second origin.

   Bucket name

   For example storify-media.

   Access key ID

   From the API token.

   Secret access key

   From the API token. Save it now: Cloudflare does not show it again.

   Account ID

   32 characters, from the R2 overview page.

   Public URL

   For example https://pub-xxxx.r2.dev, or your own domain. Without it, images do not show.

   CORS rule for the bucket

   jsonCopy

   [
     {
       "AllowedOrigins": ["https://your-store-url"],
       "AllowedMethods": ["PUT", "GET", "HEAD"],
       "AllowedHeaders": ["content-type"],
       "ExposeHeaders": ["ETag"],
       "MaxAgeSeconds": 3600
     }
   ]

   R2 is free up to a monthly allowance, but the checkout may still ask for a card or PayPal. Cloudflare limits traffic to r2.dev addresses and says they are for testing. For a live store, it recommends connecting your own domain to the bucket instead (Storage & Media). The CORS rule lets the admin upload large files straight to the bucket. The Cloudflare labels may differ slightly from the ones here.

   Check: You have saved the five values above, and the bucket's Settings page shows your CORS policy. The installer's Test connection button checks them later.

9. 9

   Continue with your path

   You now have everything the install needs. Open the chapter for your path. Each one ends with the First Run & Installer and the Launch Checklist.

   1. 1Dokploy, a control panel on your own server: Deploy with Dokploy.
   2. 2Vercel, with no server to manage (a live store needs the Pro plan): Deploy to Vercel.
   3. 3A plain Linux server that you manage yourself: Deploy to a VPS.
   4. 4Your own computer, to try Storify out: Set Up Your Computer.
   5. 5Not sure yet? Compare the paths in Choose Your Path.

Do this once on the computer where you will run Storify. You need it for a local install. You also need it if you host on Vercel: Vercel has no terminal, so maintenance commands such as pnpm create-admin or pnpm db:migrate run from your own computer. You install Node.js 24, turn on pnpm, and download the packages the project needs.

1. 1

   Find the app folder

   The app folder is the one that contains package.json. Every command in this chapter runs in that folder.

   Check: The app folder contains package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .pnpmfile.cjs, .nvmrc and .env.example. Files whose names start with a dot are hidden on macOS and Linux: press Cmd+Shift+. in Finder, or Ctrl+H in most Linux file managers, to see them.

2. 2

   Install Node.js 24

   Node.js is the program that runs Storify. Install version 24 LTS (LTS means long-term support). Storify needs at least Node.js 22.12.

   1. 1Open nodejs.org/en/download.
   2. 2In the version menu, pick the version that starts with v24 and is marked LTS, for example v24.21.0. Do not pick a higher number, such as v26.
   3. 3Windows: click Windows Installer (.msi). macOS: click macOS Installer (.pkg). The labels may differ slightly. Linux: use the nvm commands in the second box below instead.
   4. 4Run the installer and keep the default options. On Windows, one screen is called Tools for Native Modules: leave its box unticked. Storify does not need those tools.
   5. 5Close every terminal window that is already open. A terminal is the window where you type commands.
   6. 6Open a new terminal. Windows: press Start, type cmd and press Enter. macOS: open Terminal from Applications → Utilities.
   7. 7Run node -v.

   Check the version

   bashCopy

   node -v

   Linux (or macOS): install with nvm instead

   bashCopy

   # Ubuntu without curl? First run: sudo apt install curl
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
   # close the terminal, open a new one, then:
   nvm install 24
   nvm alias default 24
   node -v

   Already have Node.js? Run node -v first. If it prints v22.12.0 or higher, keep it and go to the next step.

   Check: node -v prints v24 followed by more numbers, for example v24.21.0. Any version from v22.12.0 works. Version 25 or newer needs one extra command in the next step.

3. 3

   Turn on pnpm

   pnpm is the tool that downloads Storify's packages. Node.js includes a helper called Corepack that fetches the exact pnpm version the project asks for, 10.24.0. You turn it on once.

   1. 1Run corepack enable in any terminal window.
   2. 2Windows: if you see a permission error (EPERM), open Command Prompt as administrator (Start → type cmd → right-click Command Prompt → Run as administrator). Run corepack enable there, then close that window.
   3. 3macOS or Linux: if you see a permission error (EACCES), run sudo corepack enable and type your computer password.
   4. 4If the terminal says corepack is not recognized or not found, you have Node.js 25 or newer, which no longer includes Corepack. Run npm install -g corepack first (on macOS or Linux, put sudo in front if it reports a permission error), then corepack enable.

   bashCopy

   corepack enable

   Check: corepack enable prints nothing when it works. You check the pnpm version in "Install the project's packages" below.

4. 4

   Open a terminal in the app folder

   From here on, every command must run inside the app folder, the one with package.json.

   1. 1Windows: open the app folder in File Explorer, click the address bar at the top, type cmd and press Enter. A Command Prompt opens in that folder.
   2. 2macOS: open Terminal, type cd and a space, drag the app folder from Finder into the Terminal window, then press Enter.
   3. 3Linux: right-click inside the folder in your file manager → Open in Terminal, or cd into the folder.

   Check that you are in the right folder

   bashCopy

   # Windows
   dir package.json
   
   # macOS or Linux
   ls package.json

   Keep this window open. You use it for the rest of this chapter and for Environment Variables.

   Check: The command lists package.json. If it says File Not Found, Cannot find path or No such file or directory, you are in the wrong folder.

5. 5

   Install the project's packages

   First check the pnpm version. Then pnpm downloads everything Storify needs into a new node_modules folder. The first install can take several minutes.

   1. 1Run pnpm -v. The first time, Corepack may ask Do you want to continue? [Y/n] before it downloads pnpm. Type Y and press Enter.
   2. 2Run pnpm install and wait until you can type again.

   bashCopy

   pnpm -v
   pnpm install

   ERR_PNPM_UNSUPPORTED_ENGINE means the Node.js or pnpm version is wrong. Check node -v. If pnpm -v did not print 10.24.0, remove any pnpm you installed another way (for example with npm uninstall -g pnpm), run corepack enable again and open a new terminal. ERR_PNPM_LOCKFILE_CONFIG_MISMATCH means hidden files such as .pnpmfile.cjs or pnpm-workspace.yaml were lost while copying: unzip the download again with hidden files shown.

   Check: pnpm -v prints 10.24.0, and pnpm install ends with a line like Done in … using pnpm v10.24.0. A node_modules folder now sits next to package.json. Yellow WARN lines are normal. A line with ERR_PNPM is not.

Environment variables are settings Storify reads when it starts: where the database is, the secret that protects sign-ins, and the store's web address. On your computer they live in a plain text file named .env in the app folder. On Vercel or Dokploy you type them into the hosting panel instead. Six values are enough to start. Everything else is optional, and most of it can also be set later in the admin panel.

1. 1

   Have your two secrets ready

   BETTER_AUTH_SECRET and CRON_SECRET need long random values. Use the two you made in "Generate your secrets" in Before You Install. If you have none yet, run this command twice. It works on Windows, macOS and Linux.

   bashCopy

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

   Run the command once for every secret you need, now or later (for example MESSAGING_ENCRYPTION_KEY). Copy the line it prints, never the command itself. Save each value in a password manager.

   Check: Each run prints one line of 64 characters, only digits and the letters a to f. Your two values are different.

2. 2

   Create the .env file (local install)

   In the terminal that is open in the app folder, create a file named exactly .env and open it in a text editor.

   1. 1Windows: run notepad .env. If Notepad asks whether to create a new file, click Yes.
   2. 2macOS: run touch .env and then open -e .env. The file opens in TextEdit.
   3. 3Linux: run nano .env. Save with Ctrl+O and Enter, close with Ctrl+X.

   Windows hides file extensions, so a file saved as .env.txt still looks like .env in File Explorer. Storify ignores that file. The dir .env check below shows the real name.

   Check: dir .env (Windows) or ls -a .env (macOS and Linux) lists a file named exactly .env, in the same folder as package.json.

3. 3

   Fill in the six local values

   Paste this block into .env. Replace both <64 characters> placeholders, including the < and >, with your two secrets, and save the file. Start from this block, not from a copy of .env.example.

   .env (local)

   bashCopy

   MONGODB_URI=mongodb://localhost:27017/storify
   MONGODB_DB_NAME=storify
   BETTER_AUTH_SECRET=<64 characters>
   BETTER_AUTH_URL=http://localhost:3000
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   CRON_SECRET=<64 characters>

   Keep MONGODB_URI as shown if MongoDB runs on your computer (Docker or Community Server). Using MongoDB Atlas? Put your Atlas string there instead. Database Setup explains both. Whenever you change .env later, stop pnpm dev with Ctrl+C and start it again.

   Check: The file has six lines in the form NAME=value, with no spaces around = and no < or > left. Later, the installer's System check shows the Authentication secret row in green.

4. 4

   Production: enter the values in your hosting panel

   On a server you use the production values from your notes ("Write down your environment values" in Before You Install). Vercel and Dokploy have no .env file to edit: you enter the values in the hosting panel, before the first deploy.

   Vercel

   Settings → Environment Variables. Add ENABLE_EXPERIMENTAL_COREPACK=1 too. See Deploy to Vercel.

   Dokploy

   The application's Environment tab. Add NIXPACKS_NODE_VERSION=24 too. See Deploy with Dokploy.

   VPS

   A .env file in the app folder on the server. See Deploy to a VPS.

   Enter only the variables you fill in yourself. Do not paste the whole .env.example: the app treats its placeholders as real values. The fake STORAGE_* keys make the installer skip the storage step, ADMIN_PASSWORD=change-me becomes the password pnpm create-admin gives, and CRON_SECRET=replace-with-a-long-random-secret passes as a real secret.

   Check: The panel lists all six names, spelled exactly as in the table above, plus the extra one for Vercel or Dokploy. No value still contains < or >.

5. 5

   Rebuild after you change a NEXT_PUBLIC_ value

   Values whose names start with NEXT_PUBLIC_ are copied into the app when it is built. After you change one, a restart is not enough: rebuild as shown here.

   Your computer

   Stop pnpm dev with Ctrl+C and start it again. If you use pnpm start, run pnpm build first.

   Vercel (rebuild)

   Deployments → ⋯ next to the latest deployment → Redeploy, with "Use existing Build Cache" unticked.

   Dokploy (rebuild)

   Click Deploy on the application's General tab.

   VPS (rebuild)

   Run pnpm build, then sudo systemctl restart storify.

   Other values, such as BETTER_AUTH_URL, need only a restart: on Vercel a Redeploy, on Dokploy a Reload, on a VPS sudo systemctl restart storify.

Storify keeps everything in MongoDB: products, orders, customers, users and settings. This chapter is for a local install: you need a running MongoDB and its address in your .env file. Pick one of the three options below. The app creates its collections and indexes by itself the first time it starts, so there is nothing to import. Deploying to a server instead? Your deploy chapter covers the database.

1. 1

   Option A: use MongoDB Atlas

   Atlas is MongoDB's own cloud service, and its Free tier is enough for testing. Create the cluster, the database user and the connection string as described in "Create the MongoDB database" and "Build your MongoDB connection string" in Before You Install.

   1. 1Allow your own computer: Security → Database & Network Access → IP Access List → Add IP Address → Add Current IP Address → Confirm. The exact labels may differ slightly.
   2. 2If your internet provider gives you a new IP address later, the connection stops working. Add the new address the same way.
   3. 3Will the same Atlas cluster hold your live store later? Test with another database name, for example storify-dev, in both MONGODB_URI and MONGODB_DB_NAME. The installer runs only once per database.

   Special characters in the database password break the string. Replace them (@ → %40, : → %3A, / → %2F, # → %23, ? → %3F, % → %25) or give the user a password with letters and digits only.

   Check: You have a connection string like mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority, with your real password in place of PASSWORD and /storify before the ?.

2. 2

   Option B: run MongoDB in Docker

   Docker runs programs in isolated containers. Use this option if Docker Desktop is installed and running (get Docker Desktop). One command downloads MongoDB 7 and starts it on port 27017.

   bashCopy

   docker run -d --name storify-mongo -p 27017:27017 mongo:7

   After you restart your computer, open Docker Desktop and start the database again with docker start storify-mongo. The data stays until you remove the container. Your MONGODB_URI is mongodb://localhost:27017/storify.

   Check: docker ps lists a container named storify-mongo whose status starts with Up.

3. 3

   Option C: install MongoDB Community Server

   This installs MongoDB directly on your computer as a background service. Your MONGODB_URI is then mongodb://localhost:27017/storify.

   1. 1Windows: open the MongoDB download page, choose Platform Windows and Package msi, click Download and run the file.
   2. 2Windows: choose Complete, make sure Install MongoD as a Service is ticked, keep the default service settings and click Install. MongoDB Compass, a visual database browser, is optional.
   3. 3macOS: install Homebrew from brew.sh if you do not have it yet, then run the three commands below.
   4. 4Linux: follow MongoDB's guide for your distribution.

   macOS (Homebrew)

   bashCopy

   brew tap mongodb/brew
   brew install mongodb-community
   brew services start mongodb-community

   Check: Windows: the Services app (Start → type Services) shows the MongoDB service as Running. macOS: brew services list shows mongodb-community as started.

4. 4

   Put the connection string in .env

   Open .env in the app folder, set these two lines and save. If pnpm dev is already running, stop it with Ctrl+C and start it again.

   MONGODB_URI (Docker or Community Server)

   mongodb://localhost:27017/storify. It is already in your .env if you used the block from Environment Variables.

   MONGODB_URI (Atlas)

   Your Atlas string, for example mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority.

   MONGODB_DB_NAME

   The same name as in your MONGODB_URI: storify, or your test name (for example storify-dev) if you chose one in Option A. This value wins over the name in the string. Set it with every option: without it, an Atlas string with no database name makes the app use a database called test.

   The terminal shows ECONNREFUSED when the app starts? MongoDB is not running on your computer. Docker: open Docker Desktop and run docker start storify-mongo. Community Server: start the MongoDB service (Windows: the Services app; macOS: brew services start mongodb-community).

   Check: When you start the app in Running Locally, the installer's System check shows the MongoDB connection row in green.

5. 5

   Optional: load the demo store instead of the installer

   pnpm db:seed fills the database with a complete demo store and demo logins, and the installer then stays closed. Run it now, before you open the site for the first time. "Instead of the installer (developers)" in First Run & Installer explains all the options.

   bashCopy

   pnpm db:seed
   # or another template:
   pnpm db:seed --template=women-fashion

   The demo passwords are public: use the seed for a private test only. If it stops with a message that ends in nothing was written, the database already holds other data: use an empty database name, for example storify-demo, in both MONGODB_URI and MONGODB_DB_NAME.

   Check: Near the end the output shows Database seeded successfully! and a Demo Credentials: list, for example admin@storify.com / Admin@123.

Start the store on your own computer, open it in your browser and run the installer. Use this to try Storify or to work on the code. A live store runs on a server instead: see the Deploy to Production chapters.

1. 1

   Start the dev server

   The dev server runs the whole store on this computer: storefront, admin, vendor and staff areas. It runs only while its terminal window stays open.

   1. 1Open a terminal in the app folder (the folder with package.json). On Windows, open the folder in File Explorer, click the address bar, type cmd and press Enter.
   2. 2Run pnpm dev.
   3. 3Wait for the line that starts with ✓ Ready in. Leave this window open.
   4. 4If Windows asks whether Node.js may use your networks, allowing private networks is enough. http://localhost:3000 works either way.

   bashCopy

   pnpm dev

   What the terminal shows (your numbers will differ)

   txtCopy

   ▲ Next.js 16.3.4 (webpack)
   - Local:         http://localhost:3000
   - Network:       http://192.168.1.20:3000
   - Environments: .env
   ✓ Ready in 3.2s

   If the terminal says Port 3000 is in use … using available port 3001 instead, another program already uses port 3000. Often it is an older pnpm dev window. Close that program, press Ctrl+C here and run pnpm dev again. Your .env addresses say port 3000, so the store must run there.

   Check: The Local: line shows http://localhost:3000, the Environments: line lists .env, and ✓ Ready in … appears. No Environments: line? Then Storify did not find your .env file: check that it sits next to package.json and is not named .env.txt.

2. 2

   Open the store in your browser

   Open http://localhost:3000. Type localhost, as in your .env, not 127.0.0.1. The first page can take a minute to appear, because the dev server prepares each page the first time you open it.

   Not sent to /install? An error page, or a page that loads for a long time and then fails, means Storify cannot reach your database. Pages do not redirect then. Open http://localhost:3000/install yourself: the "MongoDB connection" row shows what to fix. If the storefront opens instead, or /install shows 404, this database already has an admin. Did you load the demo store with pnpm db:seed in Database Setup? Then this is expected: skip "Run the installer" and sign in at http://localhost:3000/login with the demo logins it printed, for example admin@storify.com / Admin@123. Otherwise see "Locked out, or /install shows 404" in First Run & Installer.

   Check: The address changes to http://localhost:3000/install, and the page says "Set up your store" with "System check" below it.

3. 3

   Run the installer

   Complete the five installer screens as described in First Run & Installer. On this computer the Application URL row is green when both URL values in .env are http://localhost:3000. No storage bucket yet? Tick "Set storage up later" on the storage screen.

   Do not run pnpm create-admin or pnpm db:seed before the installer. Both create an admin account, and the installer then closes for good.

   Check: You are signed in, and http://localhost:3000/admin shows the admin dashboard. A notification titled "Background jobs have stopped" is expected here: nothing runs the scheduled jobs on your computer.

4. 4

   Try a production build (optional)

   pnpm dev is for trying and editing. A server runs a production build instead. You can test one here. The build can take several minutes.

   1. 1Stop pnpm dev with Ctrl+C. The production server needs port 3000 too.
   2. 2Windows: before your first build, run pnpm config set shell-emulator true once in this terminal. Without it, pnpm build stops with 'NODE_OPTIONS' is not recognized as an internal or external command.
   3. 3Run pnpm build. Wait until it ends with a long list of routes.
   4. 4Run pnpm start, then open http://localhost:3000.
   5. 5Changed a NEXT_PUBLIC_ value in .env later? Run pnpm build again. Those values are fixed when the app is built.

   Build, then start

   bashCopy

   pnpm build
   pnpm start

   Lines such as MongoDB connection error … or [sitemap] … emitting hub pages only mean the build could not reach the database, for example because MongoDB is not running. They are harmless: the build still finishes. Start the database before you run pnpm start.

   Check: The build log shows ✓ Compiled successfully in … and ends with a list of routes. pnpm start prints ✓ Ready in …, and http://localhost:3000 opens your store.

5. 5

   Check types and run tests (developers only)

   You need this only if you change the code. pnpm build does not check types, so run these yourself before you deploy your changes.

   bashCopy

   pnpm typecheck
   pnpm test

   More memory for typecheck: macOS and Linux

   bashCopy

   NODE_OPTIONS=--max-old-space-size=8192 pnpm typecheck

   More memory for typecheck: Windows Command Prompt

   cmdCopy

   set NODE_OPTIONS=--max-old-space-size=8192
   pnpm typecheck

   More memory for typecheck: Windows PowerShell

   powershellCopy

   $env:NODE_OPTIONS="--max-old-space-size=8192"; pnpm typecheck

   If pnpm typecheck stops with JavaScript heap out of memory, run it with more memory, using the box for your system. Storify's own automated checks give it 8 GB.

   Check: pnpm typecheck finishes without listing errors, and pnpm test ends with a summary of passed tests.

6. 6

   Stop the server

   Click the terminal window where the server runs and press Ctrl+C. Your store's data stays in the database. To continue later, open a terminal in the app folder and run pnpm dev again.

   In Command Prompt you may see Terminate batch job (Y/N)?. Type Y and press Enter.

   Check: The terminal shows its normal prompt again, and http://localhost:3000 no longer opens.

Dokploy is a free control panel that you install on your own server. From your browser, it builds Storify from your private GitHub repository, runs it, gets the HTTPS certificates and shows the logs. This chapter takes you from an empty Ubuntu server to a live store with its background jobs running.

1. 1

   Connect to the server and add swap

   Log in to the server from a terminal on your computer. Then add 4 GB of swap: disk space that Linux uses as extra memory, so a build that runs out of RAM gets slower instead of crashing the server.

   1. 1Windows: open PowerShell (press Start and type PowerShell). It has ssh built in. macOS and Linux: open Terminal.
   2. 2Run ssh root@SERVER-IP, replacing SERVER-IP with the IP address from your VPS provider (for example ssh root@203.0.113.10). If your provider gave you a user such as ubuntu, run ssh ubuntu@SERVER-IP instead.
   3. 3The first time, type yes to trust the server. Then type the password if asked. Nothing appears on the screen while you type it; that is normal.
   4. 4Run free -h. If the Swap line already shows 4.0Gi or more, skip the commands below.
   5. 5Otherwise, paste the commands below and press Enter. To paste in PowerShell, right-click or press Ctrl+V.

   Add 4 GB of swap

   bashCopy

   sudo fallocate -l 4G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
   free -h

   Add swap even on an 8 GB server. With swap, the worst case is a slow build. Without it, a build that fills the memory can freeze the whole server, including the live store.

   Check: The last free -h shows a Swap line with a total of 4.0Gi or more (more if your provider had already added some swap).

2. 2

   Install Dokploy and create your owner account

   One command installs Docker, the Dokploy panel and Traefik, the web server that sends visitors to the right app and gets its HTTPS certificate. Then you register in the panel. The first person who opens the panel becomes its owner, so register right away.

   1. 1Run sudo -i to become root. The prompt now ends with #. If you logged in as root, nothing changes.
   2. 2Paste the install command below and press Enter. It takes a few minutes.
   3. 3If it stops with This script must be run as root, run sudo -i and try again. If it stops with Error: something is already running on port 80 (or 443, or 3000), other software uses that port: start again with a fresh server.
   4. 4When it prints Congratulations, Dokploy is installed!, wait about 15 seconds. Then open http://SERVER-IP:3000 in your browser.
   5. 5On the Setup the server page, fill in First Name, Last Name, Email, Password (at least 8 characters) and Confirm Password. Click Register.
   6. 6Save the email and password in your password manager.

   Install Dokploy (as root)

   bashCopy

   curl -sSL https://dokploy.com/install.sh | sh

   Check: The message User registered successfully appears and the Dokploy dashboard opens. If a sign-in page opens instead, sign in with the same email and password.

3. 3

   Give the panel its own HTTPS address

   The panel now runs on plain http with a port number. Give it a domain with HTTPS before you connect GitHub in step 4, because the GitHub connection remembers the address you create it from.

   1. 1At your domain's DNS provider, add an A record. Name: panel (some providers want the full panel.your-domain.com). Value: your server IP. On Cloudflare, keep the record on DNS only (grey cloud) until HTTPS works.
   2. 2Wait until the name points at the server. This can take up to 30 minutes. In PowerShell or Terminal on your computer, run nslookup panel.your-domain.com: when it is ready, the last Address line shows your server IP.
   3. 3In Dokploy, open Settings → Web Server. In the Server Domain card, fill in the fields below and click Save.
   4. 4Open https://panel.your-domain.com and sign in. Use only this address from now on.

   Domain

   panel.your-domain.com

   Let's Encrypt Email

   Your real email address. Always fill this in: Dokploy uses it for every certificate, including your store's.

   HTTPS

   On

   Certificate Provider

   Let's Encrypt

   Optional, and only after the https address works: close the old http://SERVER-IP:3000 address. As root on the server, run docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy. If you do this before HTTPS works, you lock yourself out of the panel.

   Check: https://panel.your-domain.com opens the Dokploy sign-in page with a padlock in the address bar. The first certificate can take a minute; reload the page if the browser warns at first.

4. 4

   Connect GitHub

   Dokploy needs permission to read your private Storify repository. You give it by creating a small GitHub App from the panel, on the https address from step 3. Path B does not need this step.

   1. 1In Dokploy, open Settings → Git and click Github.
   2. 2Leave GitHub URL as it is. Turn on Organization? only if the repository belongs to a GitHub organization, and type the organization's name.
   3. 3Click Create GitHub App. GitHub opens with a suggested app name. Keep it (the name must be unique) and confirm the creation on GitHub.
   4. 4Back on the Dokploy Git page, the new entry shows Action Required. Click the install icon next to it.
   5. 5On GitHub, choose your account, pick Only select repositories, select your Storify repository, and click Install & Authorize.

   Did you create the GitHub App from http://SERVER-IP:3000? Then GitHub sends its push messages to that address, and automatic deploys stop once port 3000 is closed. Delete the entry on the Git page and create it again from https://panel.your-domain.com.

   Check: The Git page lists your GitHub App without the Action Required label. In step 7, your repository appears in the Repository list.

5. 5

   Create the project

   A project keeps the store and its database together in one place.

   1. 1Click Projects in the sidebar, then Create Project.
   2. 2Fill in the fields below and click Create.
   3. 3Open the new project. Dokploy adds a production environment inside it automatically; everything you create next goes there.

   Name

   Storify

   Description

   Optional. You can leave it empty.

   Check: The project page shows No services added yet. Click on Create Service.

6. 6

   Create the MongoDB database

   Storify keeps all store data in MongoDB. Choose one option. A: MongoDB runs inside Dokploy, on this server. B: MongoDB Atlas, a database hosted by MongoDB. The fields below are for option A.

   1. 1Option A: in the project, click Create Service → Database. Select MongoDB, fill in the fields below, and click Create.
   2. 2Open the new database. On its General tab, click Deploy, then Confirm. Wait a minute or two.
   3. 3In the Internal Credentials card, copy the Internal Connection URL. Copy it, do not type it: the host name has a random ending, like storify-mongo-ab12cd.
   4. 4Add the database name: type storify right after 27017/, before the ? (see the example below).
   5. 5Leave External Port (Internet) in the External Credentials card empty. Setting it would open the database to the whole internet.
   6. 6Option B: follow the steps "Create the MongoDB database" and "Build your MongoDB connection string" in Before You Install. In the Atlas IP Access List, add your server's IP address.
   7. 7Keep the final connection string in your notes. You paste it as MONGODB_URI in step 8.

   Name

   mongo

   App Name

   Keep the suggested value, for example storify-mongo. Dokploy adds a random ending.

   Database User

   mongo (the default)

   Database Password

   Leave it empty and Dokploy creates a safe one. If you type your own, use letters and digits only.

   Docker image

   Leave it empty (Dokploy uses mongo:8).

   Use Replica Sets

   Off

   Option A: a finished MONGODB_URI (your password and host name differ)

   txtCopy

   mongodb://mongo:PASSWORD@storify-mongo-ab12cd:27017/storify?authSource=admin&directConnection=true

   Which option? A costs nothing extra and keeps everything on one server, but it uses the server's memory and you set up its backups yourself (step 15). B keeps the database off your server; the free Atlas tier (M0, 512 MB) has no automatic backups.

   Check: You have one connection string saved, and it contains /storify?.

7. 7

   Create the application and connect the repository

   The application is the store itself. Dokploy downloads your code from GitHub and builds it with Nixpacks, its default builder. The result runs in a container: a sealed package that holds the store and everything it needs.

   1. 1In the project, click Create Service → Application. Name: store. Click Create.
   2. 2Open the new application. On the General tab, go to the Provider card and choose Github.
   3. 3Fill in the fields below and click Save.
   4. 4In the Build Type card, choose Nixpacks (it is usually selected already) and click Save.
   5. 5No GitHub? The Provider card's Drop tab accepts a .zip of the app folder instead (with its hidden files, without node_modules and .next). There are no automatic deploys then: every update is a new zip upload.

   Github Account

   The GitHub App from step 4

   Repository

   Your private Storify repository

   Branch

   main

   Build Path

   /

   Trigger Type

   On Push

   Watch Paths

   Leave empty

   Do not choose Dockerfile or Railpack. Storify has no Dockerfile that builds on the server: the one in deploy/ only packages an image that GitHub Actions has built (Path B), and on its own it stops with no prebuilt .next/. Railpack is not tested with Storify and can leave out .pnpmfile.cjs, which makes the package install fail.

   Check: The Provider card shows your repository and the branch main, and the Build Type card shows Nixpacks.

8. 8

   Add the environment variables

   Dokploy gives these values to the build and to the running store. NIXPACKS_NODE_VERSION=24 makes the build use Node.js 24, and the two BUILD_ lines help the build fit on a 4 GB server.

   1. 1Open the application's Environment tab.
   2. 2Paste the block below into the Environment Settings box.
   3. 3Replace the MONGODB_URI value with your string from step 6. Replace each <…> with your own 64-character secret, and remove the < and > too.
   4. 4In both URL lines, replace shop.your-domain.com with your store address: exactly what shoppers will type, starting with https://, with no / at the end. Sign-in on any other address fails with 403 Invalid origin.
   5. 5On a server with 8 GB of RAM or more, you may delete the two BUILD_ lines.
   6. 6Click Save.
   7. 7Later changes: after you change a NEXT_PUBLIC_ value, click Deploy, because that value is built into the app (Path B: change it in GitHub instead, as step 17 shows). For other changes, Reload is enough (deleting a variable needs Deploy).

   Environment Settings

   bashCopy

   MONGODB_URI=mongodb://mongo:PASSWORD@storify-mongo-ab12cd:27017/storify?authSource=admin&directConnection=true
   MONGODB_DB_NAME=storify
   BETTER_AUTH_SECRET=<64 characters from the secret command>
   BETTER_AUTH_URL=https://shop.your-domain.com
   NEXT_PUBLIC_APP_URL=https://shop.your-domain.com
   CRON_SECRET=<a different 64 characters>
   NIXPACKS_NODE_VERSION=24
   BUILD_MAX_CPUS=2
   BUILD_TURBOPACK_MEMORY_MB=3072

   Do not paste the whole .env.example file here. Its placeholder values count as real: the STORAGE_* placeholders make the installer skip the storage step, ADMIN_PASSWORD=change-me becomes the password pnpm create-admin gives, and CRON_SECRET=replace-with-… passes as a real secret. Add only the variables you actually fill in.

   Check: After you reload the page, the Environment Settings box still shows your lines, with your own values and no < or > left.

9. 9

   Point your store domain at the server and add it

   Create the DNS record first and add the domain in Dokploy second. In this order, Traefik gets the HTTPS certificate straight away.

   1. 1At your DNS provider, add an A record. Name: shop (or @ for the bare domain). Value: your server IP. On Cloudflare, keep it on DNS only (grey cloud) until HTTPS works.
   2. 2Wait until nslookup shop.your-domain.com shows your server IP in its last Address line (up to 30 minutes).
   3. 3In the application, open the Domains tab and click Add Domain.
   4. 4Fill in the fields below and click Create.

   Host

   shop.your-domain.com

   Path

   /

   Container Port

   3000

   HTTPS

   On

   Certificate Provider

   Let's Encrypt

   Domain changes work without a new deploy. The dice button next to Host creates a free …sslip.io test address, but it is HTTP only: fine for a quick look, not for the installer when your URL variables start with https://.

   Check: The domain appears in the list, and its Validate DNS button reports DNS Valid.

10. 10

    Deploy the store

    The first deploy downloads the code, installs the packages and builds the store. As a rough guide, it takes 3–10 minutes, longer on a small server.

    1. 1Open the General tab, click Deploy, then Confirm. Dokploy switches to the Deployments tab.
    2. 2The new row shows running. Click View to follow the build log.
    3. 3The line Nixpacks build completed. means the build worked. The store starts a few seconds later.
    4. 4When the row shows done, open https://shop.your-domain.com.
    5. 5If you see an error page instead of the installer, open https://shop.your-domain.com/install directly. Its System check shows what is wrong.

    With the Dokploy database (option A), the log shows several MongoDB connection error … ENOTFOUND lines and a [sitemap] … emitting hub pages only line. They are expected and harmless: the build cannot see that database, but the running store can. A real failure ends with Nixpacks build failed.

    Check: The row shows done, and https://shop.your-domain.com sends you to /install.

11. 11

    Run the installer

    Do this now. Until an admin exists, the first person who opens the installer becomes the store owner.

    1. 1Open https://shop.your-domain.com/install (the store sends you there by itself).
    2. 2Complete the five steps as described in First Run & Installer: System check, admin account, store basics, media storage and template.
    3. 3If a System check row shows a yellow warning triangle, fix that value in the Environment tab → Save → Deploy. Wait for done, then click Check again (or reload the page if that button is not shown).

    Do not run pnpm create-admin or pnpm db:seed before the installer. Both create an admin, and from then on /install answers 404 for good.

    Check: The installer shows Your store is ready. Go to sign in opens /login, and after you sign in, /admin shows the dashboard. A "Background jobs have stopped" notice there is expected: you add the jobs in the next step.

12. 12

    Schedule the 14 background jobs

    Storify has 14 background jobs (cron jobs: tasks that run on a timer), and Dokploy runs none of them by itself. You add them as 8 schedules, one for each command block below. Each command runs inside the store's container, where CRON_SECRET is already set.

    1. 1Open the application's Schedules tab and click Add Schedule.
    2. 2Fill in the fields below. For Command, click Copy on the matching block below and paste it as it is.
    3. 3Click Create Schedule.
    4. 4Repeat for all 8 blocks.

    Task Name

    The name in the block's title, for example storify-every-minute

    Schedule

    The cron expression in the block's title, for example * * * * *. Type it into the box under the preset list (the one that says Custom cron expression).

    Timezone

    Leave empty (UTC)

    Shell Type

    Bash

    Command

    The whole command from that block

    Enabled

    On

    storify-every-minute (* * * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" messaging-outbox carrier-shipments

    storify-every-5-min (*/5 * * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" email-deliveries messaging-escalations boosts

    storify-every-15-min (*/15 * * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" orange-money-reconcile mtn-momo-reconcile abandoned-checkouts

    storify-every-30-min (*/30 * * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" carrier-tracking checkout-expiry

    storify-hourly (0 * * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" vendor-subscriptions

    storify-disputes (40 * * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" gateway-disputes

    storify-finance (0 3 * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" finance

    storify-preorders (0 4 * * *)

    bashCopy

    node -e "Promise.all(process.argv.slice(1).map(p=>fetch('http://localhost:3000/api/cron/'+p,{headers:{authorization:'Bearer '+process.env.CRON_SECRET}}).then(r=>{console.log(p,r.status);if(!r.ok)process.exitCode=1})))" preorders

    A 401 in the run log means CRON_SECRET is missing from the Environment tab, or was changed and not applied yet. Fix it, click Reload, and run the schedule again. A run that gets 401 is not recorded, so the dashboard reports that job as never run.

    Check: The Schedules tab lists 8 schedules. Click the play button (Run Manual Schedule) on storify-every-minute, then the list icon next to it: the run log shows messaging-outbox 200, carrier-shipments 200 and Command executed successfully. After an hour, a new "Background jobs have stopped" notice should name at most vendor-subscriptions, gateway-disputes, finance and preorders; after a day it should not appear at all. If it still names messaging-outbox or carrier-shipments after an hour, the schedules are not running.

13. 13

    Keep the image cache across deploys (optional)

    Storify saves resized product images in /app/.next/cache. A volume (storage that survives a new deploy) keeps that folder, so the first visitors after an update do not wait while every image is resized again.

    1. 1Open the Advanced tab. In the Volumes card, click Add Volume.
    2. 2Choose Volume Mount, fill in the fields below, and click Create.
    3. 3Open the General tab and click Reload to apply it. No rebuild is needed.

    Volume Name

    storify-next-cache

    Mount Path (In the container)

    /app/.next/cache

    Check: The Volumes card lists the mount path /app/.next/cache.

14. 14

    Run commands inside the container when you need them

    Some tasks, such as migrations after an update, are commands you run inside the store's container. Dokploy has a terminal for this in the browser.

    1. 1On the General tab, click Open Terminal. In the Docker Terminal window, pick the store's container under Select a container, and keep Bash.
    2. 2The terminal starts in /. Each time you open it, first run cd /app && touch .env. The scripts need a .env file to exist; an empty one is fine, because the Environment tab values still apply. Every deploy makes a new container, so the file does not stay.
    3. 3If a command answers pnpm: command not found, run bash -l, then run the command again.
    4. 4Locked out of the admin? pnpm create-admin you@your-domain.com "NewStrongPassword" resets that user's password. See First Run & Installer.

    First commands in the terminal

    bashCopy

    cd /app && touch .env
    pnpm db:migrate --list

    Never type commands into Advanced → Run Command. That field replaces the store's start command, so the store stops working.

    Check: pnpm db:migrate --list prints Storify's migrations, grouped by release.

15. 15

    Back up the database

    Set up backups before the store takes real orders. How you do it depends on the database you chose in step 6.

    1. 1Option A (Dokploy MongoDB): create a private bucket just for backups, with its own access key. Cloudflare R2 works; Storage & Media shows how to create a bucket and a key.
    2. 2In Dokploy, open Settings → S3 Destinations → Add Destination. For R2: Name backups, Provider Cloudflare R2 Storage, your Access Key Id and Secret Access Key, Bucket = the backup bucket's name, Region auto, Endpoint https://ACCOUNT-ID.r2.cloudflarestorage.com. Click Test Connection, then Create.
    3. 3Open the MongoDB service → Backups tab → Create Backup. Fill in the fields below and click Create.
    4. 4Click Run Manual Backup on the new row to test it now.
    5. 5Option B (Atlas): the free M0 tier has no automatic backups. Use a paid Atlas tier with backups, or mongodump as shown in "Set up backups" in Launch Checklist.
    6. 6Either way, keep a copy of your Environment tab values in your password manager.

    Destination

    The destination you just added

    Database

    storify

    Schedule

    0 2 * * * (every night at 02:00 UTC)

    Keep the latest

    14 (if empty, every backup is kept)

    Enabled

    On

    Never put backups in the public bucket that serves your product images. A backup holds your customers' data.

    Check: After Run Manual Backup, a new backup file appears in your backup bucket.

16. 16

    Install a future update

    A new Storify release arrives as a new zip from CodeCanyon. You put the new files into your repository, and Dokploy rebuilds by itself when you push.

    1. 1Read that release's notes in Updates & Migrations, and back up the database first (step 15).
    2. 2Show hidden files (Windows Explorer: View → Show → Hidden items; macOS Finder: Cmd+Shift+.). In your local repository folder, delete everything except the hidden .git folder, then copy in everything from the new release's app folder, hidden files included. Otherwise, files that the new release removed stay behind and can break the build. If you changed Storify's code yourself, apply those changes again. Never copy a .env file into it.
    3. 3Commit and push. In GitHub Desktop: Commit to main, then Push origin. On the command line: the commands below.
    4. 4Dokploy starts a new deployment by itself (the Autodeploy switch on the General tab is on by default). Follow it in the Deployments tab.
    5. 5When it shows done, open the terminal (step 14) and run the migrations the release notes list, for example pnpm db:migrate <name>.
    6. 6Your Environment tab values stay as they are. Add only the new variables the release notes ask for.
    7. 7Path B: the push starts the Deploy image workflow instead. Dokploy redeploys by itself if you added the three DOKPLOY_ secrets (step 18); otherwise click Deploy after the run turns green.

    Command line instead of GitHub Desktop

    bashCopy

    git add .
    git commit -m "Update Storify"
    git push

    Dokploy itself updates separately. As root on the server, run curl -sSL https://dokploy.com/install.sh | sh -s update.

    Check: The Deployments tab shows a new done row, and /admin opens with your products and orders.

17. 17

    Advanced: build the image in GitHub Actions (Path B)

    Use this instead of step 10 when the server should never build. GitHub builds the store into an image (a ready-to-run package of the store) and stores it in your GitHub account. Dokploy then only downloads and starts it (step 18).

    1. 1Check that your repository contains .github/workflows/deploy-image.yml. It ships with Storify, but a folder whose name starts with a dot is easy to leave out, because Windows and macOS hide it.
    2. 2On GitHub, open your repository → Settings → Secrets and variables → Actions.
    3. 3Variables tab → New repository variable: Name NEXT_PUBLIC_APP_URL, Value https://shop.your-domain.com. It is built into the image, so changing it in Dokploy has no effect; to change it later, edit this variable and run the workflow again. Add any other NEXT_PUBLIC_ values you use here too.
    4. 4Secrets tab → New repository secret: Name BUILD_MONGODB_URI, Value = the same connection string as your MONGODB_URI. The workflow stops if it is missing.
    5. 5The build does not need to reach the database. If it cannot (the Dokploy database, or Atlas without 0.0.0.0/0), the log shows MongoDB connection error lines and the build still finishes; the sitemap fills in once the store runs.
    6. 6Open the Actions tab → Deploy image → Run workflow, and confirm with the green Run workflow button. Pushing a commit to main also starts it.
    7. 7When the run is green, open your GitHub profile → Packages. The image is listed there as a private package, named after your repository.

    If Deploy image is missing from the Actions tab, if GitHub reports Invalid workflow file, or if the run fails before its Build step, stop here and contact Storify support with a screenshot of the run. Do not edit the workflow yourself. You can use Path A (step 10) meanwhile.

    Check: The Actions tab shows a green check next to the Deploy image run, and your Packages page lists the image.

18. 18

    Advanced: run the prebuilt image in Dokploy (Path B)

    Now let the application download your image instead of building code. The Environment tab, domain, schedules, volume and terminal work exactly as in Path A. When the store runs, continue at step 11.

    1. 1On GitHub, create a token that lets Dokploy download the image: profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Tick only read:packages. Pick an expiration you will remember: when the token expires, deploys fail. Generate it and copy it.
    2. 2In Dokploy, open Settings → Registry → Add Registry. Registry Name ghcr, Username = your GitHub username, Password = the token, Registry URL ghcr.io. Leave Image Prefix empty. Click Test Registry, then Create.
    3. 3In the application's General tab, open the Provider card → Docker. Docker Image: ghcr.io/YOUR-USERNAME/storify:main (your GitHub username and repository name, in lowercase). Click Save.
    4. 4Click Deploy, then Confirm. The log downloads the image instead of building it.
    5. 5To roll back, set Docker Image to an older tag from the package page. Each tag is a short commit ID, for example ghcr.io/YOUR-USERNAME/storify:8a45278 (no sha- in front). Then click Deploy.
    6. 6Automatic redeploys (optional): in Dokploy, open Settings → Profile → API/CLI Keys → Generate New Key. Then add three GitHub secrets: DOKPLOY_URL = https://panel.your-domain.com (no / at the end), DOKPLOY_API_KEY = the key, DOKPLOY_APPLICATION_ID = the ID after /application/ in the application's address in your browser (stop before any ?).
    7. 7Without these three secrets, click Deploy in Dokploy after each green run.

    If the log shows Pulling image failed with denied or unauthorized, check that the token has not expired. Then also fill in Registry URL ghcr.io, Username and Password (the token) in the Docker provider card, click Save, and deploy again.

    Check: The deployment row shows done, its log contains Pulling image completed., and https://shop.your-domain.com opens (on a new store, it sends you to /install).

Vercel runs Storify for you: there is no server to manage, HTTPS is included, and the 14 background jobs run by themselves. You import your private GitHub repository, add seven settings, click Deploy and run the installer. Follow the steps in order. The settings must be in place before the first build, and the installer should run right after it.

1. 1

   Choose a Vercel team on the Pro plan

   Every Vercel project belongs to a team. Create the Storify project in a team on Pro or on the Pro trial, not in your Hobby team.

   1. 1Sign in at vercel.com.
   2. 2Open the team switcher: click the team name at the top left of the dashboard.
   3. 3Already have a Pro team? Select it and go to step 2.
   4. 4To start the free trial: at the bottom of the team switcher choose Create Team, enter a name (for example your store's name) and choose the Pro Trial option. If Pro Trial is not offered, your account has already used its one trial.

   The trial lasts 14 days. To stay on Pro, add a payment method under the team's Settings → Billing before it ends. Without one, the team goes back to Hobby, and a live store must run on Pro.

   Check: The team switcher shows your Pro or Pro Trial team as the selected team. Keep it selected for all the next steps.

2. 2

   Import your GitHub repository

   Create the project from your private repository. From now on, every push to its main branch builds and publishes a new version of the store. Do not use Vercel Drop (zip upload) instead: it builds before you can add the settings, and it creates a new project every time.

   1. 1In the dashboard, click Add New… → Project.
   2. 2Under Import Git Repository, choose GitHub. If Vercel asks, sign in to GitHub and install Vercel's GitHub app.
   3. 3Your repository is not in the list? Click the link to adjust the GitHub app permissions (the wording may differ slightly). On GitHub, choose Only select repositories, pick your Storify repository and save.
   4. 4Click Import next to your Storify repository.
   5. 5Fill in the configure screen as shown below. Do not click Deploy yet.

   Project Name

   storify, or another short name. It becomes your first store address: https://<project-name>.vercel.app. Write it down.

   Framework Preset

   Next.js. Vercel detects it by itself; leave it.

   Root Directory

   ./ (leave it). Change it only if package.json sits in a subfolder of your repository.

   Build and Output Settings

   Leave every override switch off. A custom install command makes Vercel use an old pnpm, and the install fails.

   Environment Variables

   Fill these in next, in step 3.

   A repository in your personal GitHub account works on every plan. A repository that belongs to a GitHub organization can be imported only by a Pro team, not by a Hobby team.

   Check: The configure screen shows your repository, Framework Preset Next.js, and a Deploy button that you have not clicked yet.

3. 3

   Add the environment variables before you deploy

   Environment variables are the settings the store reads when it builds and runs. Add all seven now, on the same screen: the build and the running store need them from the first minute. ENABLE_EXPERIMENTAL_COREPACK=1 makes Vercel install with exactly the pnpm version Storify expects (10.24.0). Without it, the install can stop with ERR_PNPM_UNSUPPORTED_ENGINE.

   1. 1On the configure screen, click Environment Variables to open that part of the form.
   2. 2Copy the block below into a text editor such as Notepad and fill in your own values: your Atlas connection string, your two secrets, and your Project Name in both addresses. If Vercel later gives the project a different address, you correct it in step 5.
   3. 3Keep MONGODB_DB_NAME=storify in the list. Without it, a connection string that is missing /storify makes the store save everything in a database called test.
   4. 4Click in the first Key field and paste the whole edited block. Vercel should fill one row per line. If it does not, add each line by hand: the text before = is the Key, and the text after it is the Value.
   5. 5If each row lets you choose a type, choose Secret for MONGODB_URI, BETTER_AUTH_SECRET and CRON_SECRET, and Config for the other four. Vercel never shows a Secret value again, so keep your copies in your password manager.

   Environment variables for Vercel (fill in your own values)

   bashCopy

   MONGODB_URI=mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority
   MONGODB_DB_NAME=storify
   BETTER_AUTH_SECRET=<64 characters from Before You Install>
   BETTER_AUTH_URL=https://<project-name>.vercel.app
   NEXT_PUBLIC_APP_URL=https://<project-name>.vercel.app
   CRON_SECRET=<a different 64 characters>
   ENABLE_EXPERIMENTAL_COREPACK=1

   Do not paste the whole .env.example file. Storify treats its placeholder values as real settings: the STORAGE_* placeholders make the installer skip the storage step, and CRON_SECRET=replace-with-… would become your real job secret. Enter only the seven lines above.

   Check: The form lists seven rows, from MONGODB_URI to ENABLE_EXPERIMENTAL_COREPACK. No value has spaces around = or a leftover < or >. Both addresses start with https:// and have no / at the end.

4. 4

   Deploy and watch the build

   Vercel now installs the packages, builds the store and publishes it. The first deployment of a new project is always your production (live) deployment. It usually takes several minutes.

   1. 1Click Deploy. The build log opens. You do not need to read every line.
   2. 2A warning about "engines": { "node": ">=22.12.0" } that "will automatically upgrade when a new major Node.js Version is released" is normal. Vercel builds Storify with Node.js 24, so you do not need to set a Node.js version.
   3. 3Lines that start with MongoDB connection error or [sitemap] … emitting hub pages only mean the build could not reach your database. The build still finishes, but the running store will probably fail too. Check MONGODB_URI and the 0.0.0.0/0 entry in the Atlas IP Access List before step 6.
   4. 4Wait until Vercel shows the deployment as Ready.
   5. 5Click Continue to Dashboard, or open the project from your dashboard. The label may differ slightly.

   Build failed with ERR_PNPM_UNSUPPORTED_ENGINE? The ENABLE_EXPERIMENTAL_COREPACK=1 row is missing or misspelled (the value is exactly 1), or an Install Command override is switched on (Settings → Build and Deployment; the label may differ slightly). Fix it under Settings, then redeploy without the build cache as shown in step 5. Build failed with Hobby accounts are limited to daily cron jobs? The project is in a Hobby team: create it again in a Pro team (step 1).

   Check: The deployment's status is Ready.

5. 5

   Confirm the production address

   The production address is where shoppers find the store until you add your own domain. BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL must match it exactly. Use only this address: preview and per-deployment addresses sit behind a Vercel login, and sign-in fails there with Invalid origin.

   1. 1On the project page, look at the Domains of the production deployment. The layout may differ slightly.
   2. 2Find the .vercel.app address that does not contain -git-. That is your production address. If the plain name was already taken, which is likely for a name like storify, it has an extra part after your project name. That is still the address to use.
   3. 3It matches what you entered in step 3? Go straight to the check below.
   4. 4It is different (Vercel adds a suffix when a name is already taken)? Open Settings → Environment Variables, change BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL to the real address, and save.
   5. 5Then redeploy: open Deployments, click ⋯ next to the latest deployment, choose Redeploy, untick Use existing Build Cache and click Redeploy. NEXT_PUBLIC_APP_URL is built into the app, so it needs a fresh build.

   A Vercel login page on the production address means Deployment Protection covers every deployment. Open Settings → Deployment Protection, set Vercel Authentication to Standard Protection and click Save. Standard Protection is the default for new projects: it keeps the production address public and hides only preview addresses. With the stricter setting, shoppers and payment webhooks are blocked.

   Check: Open the production address in a private (incognito) browser window. It redirects to /install and shows the Storify installer, not a Vercel login page. An error page instead? See the tip in step 6.

6. 6

   Run the installer

   Do this now, before anyone else finds the address: the first person who completes the installer becomes the store owner. First Run & Installer explains each of its five screens.

   1. 1Open your production address. It redirects to /install.
   2. 2System check: all four rows need a green tick. If one shows a warning, change that value under Settings → Environment Variables, redeploy (step 5), then reload the installer page (the Check again button appears only while one of the first three rows fails). An Application URL warning means your two URL variables do not match the address you opened: go back to step 5.
   3. 3Create your admin account: your name, your email and a password of at least 8 characters. Save the password in your password manager.
   4. 4Store basics and Choose your storefront template: fill them in as First Run & Installer describes. You can change them later.
   5. 5Where media is stored: enter your bucket details if you have them. Otherwise tick Set storage up later and do step 7 right after the install.
   6. 6Click Install. On Your store is ready, click Go to sign in.

   The address shows an error page instead of the installer? The store cannot reach its database, so it cannot redirect you. Open https://<project-name>.vercel.app/install directly: the System check shows which setting is wrong. Usually it is the Atlas IP Access List, or special characters in the database password that are not encoded (see "Build your MongoDB connection string" in Before You Install).

   Check: You can sign in at /login with your new owner account, and /admin opens the dashboard. A notice titled "Background jobs have stopped" is normal on a new store: step 8 explains it.

7. 7

   Connect storage before anyone uploads

   Vercel cannot keep uploaded files, so every image must go to your bucket. An upload that cannot go straight to the bucket passes through Vercel instead, and Vercel accepts at most 4.5 MB per file.

   1. 1No bucket yet? Create one now: see "Create a storage bucket" in Before You Install. Other providers: Storage & Media.
   2. 2If you ticked Set storage up later, open Admin → Settings → Storage, fill in the form, click Test Connection, then save.
   3. 3Open the bucket's CORS rule. CORS is a bucket setting that lists the websites allowed to upload to it. Cloudflare R2: your bucket → Settings → CORS Policy. AWS S3: your bucket → Permissions → Cross-origin resource sharing (CORS) → Edit.
   4. 4Paste the rule below, or correct the one you added before. List your exact store addresses: https, and no / at the end. If you already know your custom domain (step 9), list it too. Save.

   Bucket CORS rule (replace both addresses)

   jsonCopy

   [
     {
       "AllowedOrigins": [
         "https://<project-name>.vercel.app",
         "https://www.your-domain.com"
       ],
       "AllowedMethods": ["PUT", "GET", "HEAD"],
       "AllowedHeaders": ["content-type"],
       "ExposeHeaders": ["ETag"],
       "MaxAgeSeconds": 3600
     }
   ]

   Without a matching CORS rule, small uploads still work, but files over 4.5 MB fail with File is too large to upload through the server. The address in the browser's address bar must appear exactly in AllowedOrigins.

   Check: Test Connection passes, and a product image you upload in the admin shows on the product page.

8. 8

   Check the scheduled jobs

   A cron job is a task the platform runs on a timer. Vercel reads Storify's 14 jobs from vercel.json, runs them on the production deployment (times are in UTC), and sends your CRON_SECRET with every call. There is nothing to set up, only to check. Scheduled Jobs lists what each job does.

   1. 1Open the project → Settings → Cron Jobs. It lists 14 jobs, such as /api/cron/messaging-outbox and /api/cron/finance.
   2. 2Next to /api/cron/messaging-outbox (it runs every minute), click View Logs. After a few minutes, each run shows the status 200.
   3. 3About an hour after the install, open /admin. A new store first shows a notice titled "Background jobs have stopped", because a job that has not had its first turn counts as stopped. After an hour, a new notice should name at most the hourly and daily jobs (vendor-subscriptions, gateway-disputes, finance, preorders). After a day it should not appear at all.
   4. 4If messaging-outbox or carrier-shipments is still named after an hour, the jobs are not running. Check View Logs and the note below.
   5. 5To call one job by hand, use "Test one job by hand" in Scheduled Jobs with your production address.

   Opening a job's address in a browser shows 401 Unauthorized. That is expected: a browser cannot send the secret. A 401 in View Logs means CRON_SECRET is missing, or was changed without a redeploy.

   Check: Settings → Cron Jobs lists 14 jobs, and View Logs for messaging-outbox shows runs with status 200.

9. 9

   Add your custom domain

   Give the store its own address, such as www.your-domain.com or shop.your-domain.com. Vercel shows the DNS records to add at the company that manages your domain (your registrar or DNS provider), and it sets up HTTPS by itself. More background: Custom Domain & SSL.

   1. 1Open the project → Settings → Domains → Add Domain.
   2. 2Enter your domain and confirm. For a main domain such as your-domain.com, Vercel offers to add www.your-domain.com as well. Accept it.
   3. 3Decide which one is your store address. Vercel recommends www.your-domain.com, with your-domain.com redirecting to it. To change the direction, click Edit on a domain and use Redirect to (the labels may differ slightly).
   4. 4Vercel now shows the records for each domain: an A record for a main domain, and a CNAME record for a subdomain such as www or shop. Copy the exact name and value it shows.
   5. 5At your DNS provider, add those records. Delete any other A, AAAA or CNAME record with the same name.
   6. 6Wait for Vercel to verify them. This often takes a few minutes, but it can take several hours.

   Never copy DNS values from a tutorial or from another project. Vercel gives each project its own values and checks for exactly those. If your DNS is at Cloudflare, set these records to DNS only (grey cloud), so that Vercel can issue the HTTPS certificate.

   Check: Settings → Domains shows each domain as Valid Configuration, with no error, and https://your-domain opens the store with a padlock in the browser's address bar.

10. 10

    Switch the store to your domain

    The store still believes its address is the vercel.app one. Point both URL variables at your domain and rebuild. Otherwise sign-in on the new domain fails with Invalid origin.

    1. 1Open Settings → Environment Variables.
    2. 2Change BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL to your store address from step 9, for example https://www.your-domain.com. Use your main address, not the one that redirects to it, with https and no / at the end. Save.
    3. 3Open Deployments, click ⋯ next to the latest deployment, choose Redeploy, untick Use existing Build Cache and click Redeploy.
    4. 4When the new deployment is Ready, open https://your-domain/login and sign in.
    5. 5Add the new address to the bucket's CORS rule (step 7) if it is not there yet.
    6. 6Point your payment webhooks and social sign-in redirect addresses at the new domain. The full list is in the Launch Checklist.

    From now on, sign-in works only on this domain. The vercel.app address still shows the shop, but signing in there fails with Invalid origin. That is expected.

    Check: You can sign in at https://your-domain/login, and /admin opens the dashboard.

11. 11

    Run the server code near your database

    Vercel runs Storify's server code in Washington, D.C. (iad1) unless you choose another region. Every page asks MongoDB for data several times, so the server code should run in the same region as your Atlas cluster. A distant region makes every page slower.

    1. 1In Atlas, open your cluster and note its cloud provider and region, for example AWS Frankfurt (eu-central-1).
    2. 2In Vercel, open the project → Settings → Functions → Function Regions.
    3. 3Select the matching region from the list below, clear any other region, and click Save.
    4. 4Redeploy (Deployments → ⋯ → Redeploy). The new region applies only to new deployments. You can keep the build cache this time.

    Atlas AWS N. Virginia (us-east-1)

    iad1 Washington, D.C. This is the default: nothing to change.

    Atlas AWS Ohio (us-east-2)

    cle1 Cleveland

    Atlas AWS Oregon (us-west-2)

    pdx1 Portland

    Atlas AWS Frankfurt (eu-central-1)

    fra1 Frankfurt

    Atlas AWS Ireland (eu-west-1)

    dub1 Dublin

    Atlas AWS London (eu-west-2)

    lhr1 London

    Atlas AWS Mumbai (ap-south-1)

    bom1 Mumbai

    Atlas AWS Singapore (ap-southeast-1)

    sin1 Singapore

    Atlas AWS Sydney (ap-southeast-2)

    syd1 Sydney

    Atlas AWS São Paulo (sa-east-1)

    gru1 São Paulo

    Is your cluster on Google Cloud or Azure? Choose the Vercel region in the same city, or the nearest one. Storify needs only one region.

    Check: Settings → Functions → Function Regions shows only the region you chose.

12. 12

    Run maintenance commands from your computer

    Vercel has no command line (shell). When you need a database command, such as an update's migrations or pnpm create-admin to get back into a locked account, run it on your own computer against the live database.

    1. 1Use a copy of the same Storify version that is live, for example the repository folder you push from. Run pnpm install in it once.
    2. 2Your computer can already reach Atlas, because the 0.0.0.0/0 entry allows every address. If you removed that entry, add your current IP address in Atlas.
    3. 3In that folder, create a file named .env with the three lines below. Use the same values as on Vercel, from your password manager: Vercel cannot show Secret values again. Git ignores .env files, so this one is never pushed.
    4. 4Using Windows Notepad? In the Save dialog, set Save as type to All files, so that the file is named .env and not .env.txt.
    5. 5Open a terminal in that folder (Windows 11: right-click inside the folder in File Explorer → Open in Terminal) and run the command you need. The commands below are the same on macOS and Linux. On Windows, pnpm create-admin works in any terminal, but pnpm db:migrate stops in Command Prompt and PowerShell with 'C:\Program' is not recognized as an internal or external command. Run the migrations from WSL2 (Ubuntu) instead: clone your repository inside WSL, install Node.js 24 and pnpm there, and create the same .env in that copy.
    6. 6When you finish, delete this .env or put your local values back, so that you cannot change the live store by accident.

    .env on your computer (it points at the LIVE database)

    bashCopy

    MONGODB_URI=mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority
    MONGODB_DB_NAME=storify
    BETTER_AUTH_SECRET=<the same value as on Vercel>

    Migrations: list them, dry-run them, then apply (read the dry run first)

    bashCopy

    pnpm db:migrate --list
    pnpm db:migrate --all --dry-run
    pnpm db:migrate --all --yes

    Locked out: reset the password of an existing admin

    bashCopy

    pnpm create-admin you@your-domain.com "NewStrongPassword"

    Never run pnpm db:seed, pnpm db:reset or pnpm db:full-reset while this .env points at the live database. They fill your store with demo data or wipe it.

    Check: pnpm db:migrate --all --dry-run reports what each migration would change and writes nothing. If you see .env: not found, the file is missing or has the wrong name.

13. 13

    Install a future update

    Every new release goes in the same way: new files into your repository, push, let Vercel build, then run the release's database migrations from your computer. First read the notes for every version you are skipping in Updates & Migrations. New scheduled jobs in vercel.json start by themselves.

    1. 1Turn on maintenance mode: Admin → Settings → Maintenance → Enable Maintenance Mode → Save Maintenance Settings.
    2. 2Back up the database: run the mongodump command from "Set up backups" in the Launch Checklist, with your live connection string typed inside the quotes. Before you go on, check that storify-backup.gz exists and is not empty.
    3. 3Show hidden files (see "Download and unzip the package" in Before You Install). In your repository folder, delete everything except the hidden .git folder, which holds your history.
    4. 4Copy in everything from the new release's app folder, hidden files included. If you changed Storify's code yourself, re-apply those changes.
    5. 5Commit and push. In GitHub Desktop: type a summary such as Update Storify, click Commit to main, then click Push origin. Vercel starts a new production build by itself.
    6. 6When the new deployment is Ready, run pnpm install in the folder, then the release's migrations from your computer (step 12): the dry run first, then apply.
    7. 7Check the store, then turn maintenance mode off.

    Command line instead of GitHub Desktop

    bashCopy

    git add .
    git commit -m "Update Storify"
    git push

    Vercel's Instant Rollback puts the previous deployment back in seconds, but it does not undo database migrations, and it does not change the active cron jobs. To go back after migrating, restore your database backup as well.

    Check: The new deployment is Ready, the migrations finish without errors, and the store works as before.

Run Storify on your own Ubuntu server, without a control panel. Node.js runs the store, systemd (Ubuntu's service manager) keeps it running and starts it again after a reboot, and Caddy (a small web server) adds HTTPS. You type every command yourself over SSH (a command line on the server that you open from your computer). This path gives you full control and asks the most of you.

1. 1

   Point your domain at the server

   Do this first, because DNS changes can take a while to reach everyone. Caddy needs this record later to get your HTTPS certificate. The examples use shop.your-domain.com as the store address.

   1. 1Sign in where your domain's DNS is managed: your domain registrar, or Cloudflare.
   2. 2Add an A record. Name: shop (or @ for the bare domain your-domain.com). Value: your server's IP address.
   3. 3Delete any older A, AAAA or CNAME record with the same name. An old AAAA record (IPv6) that points elsewhere stops the certificate.
   4. 4Using Cloudflare? Set the record's proxy status to DNS only (grey cloud) for now. See Custom Domain & SSL.

   Check: nslookup shop.your-domain.com (it works on Windows, macOS and Linux) shows your server's IP address in its last Address line. This can take from a few minutes to a few hours; carry on with the next steps meanwhile.

2. 2

   Create a user and turn on the firewall

   Log in as root once, create a normal user called storify, and let only SSH (port 22), HTTP (80) and HTTPS (443) through the firewall. Storify never runs as root.

   1. 1Connect as root: ssh root@SERVER-IP. Type yes if SSH asks whether to continue connecting. If your provider gave you a user such as ubuntu instead of root, connect with that user and run sudo -i first.
   2. 2Create the user: adduser storify. Choose a password and save it. Press Enter to skip the other questions.
   3. 3Give the user admin rights: usermod -aG sudo storify.
   4. 4Only if you log in with an SSH key (not a password): copy the key to the new user with rsync --archive --chown=storify:storify ~/.ssh /home/storify. If you connected as ubuntu, write /home/ubuntu/.ssh instead of ~/.ssh.
   5. 5Paste the block below. It opens the three ports, turns the firewall on and switches to the new user.
   6. 6From now on, connect with ssh storify@SERVER-IP.

   bashCopy

   ufw allow OpenSSH
   ufw allow 80,443/tcp
   ufw --force enable
   ufw status
   su - storify

   Some providers also have a firewall in their web panel (for example a cloud firewall or security group). Open ports 22, 80 and 443 there too.

   Check: ufw status shows Status: active with OpenSSH and 80,443/tcp allowed, and the prompt now starts with storify@.

3. 3

   Add swap memory

   Swap is disk space that Linux uses as extra memory. Building Storify needs much more memory than running it, and without swap a build on a 4 GB server can freeze the whole server. Skip this step if free -h already shows a Swap: line above 0. Run sudo -v first.

   bashCopy

   sudo fallocate -l 4G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
   free -h

   Check: free -h shows a Swap: line with about 4.0Gi in the total column.

4. 4

   Install Node.js 24 and pnpm

   nvm (Node Version Manager) installs Node.js for one user only, so run this as storify, not as root. corepack enable then provides pnpm; the exact pnpm version (10.24.0) comes from Storify's package.json.

   bashCopy

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
   source ~/.bashrc
   nvm install 24
   nvm alias default 24
   corepack enable
   node -v

   If corepack is "not found" (this happens only on Node.js 25 or newer), run npm install -g corepack and then corepack enable again.

   Check: node -v prints v24. followed by more numbers. You check the pnpm version later, inside the app folder.

5. 5

   Use MongoDB Atlas (recommended)

   Atlas runs MongoDB for you, so nothing is installed on this server. If you followed Before You Install, your connection string is ready. Check these two things, then skip the next step.

   1. 1In Atlas, open Security → Database & Network Access → IP Access List (the exact labels may differ slightly). Add this server's public IP address (the one in your A record) if it is not there yet.
   2. 2Your connection string contains /storify?, like mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority.

   The Free tier (M0, 512 MB) has no automatic backups. It is fine for testing and a first launch. For a busy live store, use a paid tier with backups (see the step "Back up the database").

   Check: The IP Access List shows your server's IP address, and your string contains .mongodb.net/storify?. The installer's "MongoDB connection" row confirms the connection later.

6. 6

   Or run MongoDB in Docker on this server

   Skip this step if you use Atlas. Docker runs MongoDB in a container (an isolated package) on this server. Backups and MongoDB upgrades are then your job. Block 1 installs Docker Engine from Docker's own package repository, as described in Docker's guide for Ubuntu.

   1. 1Run sudo -v, then paste block 1. It installs Docker and ends by printing Hello from Docker!.
   2. 2Run mkdir -p ~/mongo && nano ~/mongo/docker-compose.yml. Paste block 2, replace CHANGE-THIS-PASSWORD with a password of letters and digits only, and save.
   3. 3Paste block 3 to start MongoDB.
   4. 4Your connection string is mongodb://storify:CHANGE-THIS-PASSWORD@127.0.0.1:27017/storify?authSource=admin, with your password in it. You need it for .env.

   1. Install Docker Engine

   bashCopy

   sudo apt update
   sudo apt install -y ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
   Types: deb
   URIs: https://download.docker.com/linux/ubuntu
   Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
   Components: stable
   Architectures: $(dpkg --print-architecture)
   Signed-By: /etc/apt/keyrings/docker.asc
   EOF
   sudo apt update
   sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   sudo docker run hello-world

   2. ~/mongo/docker-compose.yml

   yamlCopy

   services:
     mongo:
       image: mongo:7
       container_name: storify-mongo
       restart: unless-stopped
       environment:
         MONGO_INITDB_ROOT_USERNAME: storify
         MONGO_INITDB_ROOT_PASSWORD: CHANGE-THIS-PASSWORD
       volumes:
         - mongodata:/data/db
       ports:
         - "127.0.0.1:27017:27017"
   
   volumes:
     mongodata:

   3. Start MongoDB

   bashCopy

   cd ~/mongo
   sudo docker compose up -d
   sudo docker ps

   Keep the 127.0.0.1: part of the ports line. Ports that Docker publishes bypass the ufw firewall, so without it MongoDB would be open to the whole internet.

   Check: sudo docker ps lists storify-mongo with a STATUS of Up … and PORTS 127.0.0.1:27017->27017/tcp.

7. 7

   Copy the files with Git (recommended)

   If your Storify code is in a private GitHub repository, let the server download it. A deploy key is an SSH key that can only read this one repository, and it makes later updates a single git pull.

   1. 1Paste block 1. It creates a key and prints one line that starts with ssh-ed25519.
   2. 2On github.com, open your repository → Settings → Deploy keys → Add deploy key.
   3. 3Title: storify-server. Key: paste the whole ssh-ed25519 … line. Leave Allow write access unticked. Click Add key.
   4. 4Paste block 2, with your GitHub user name in place of YOUR-USERNAME (and your repository name in place of storify, if it differs). Type yes when SSH asks whether to continue connecting.

   1. Create a deploy key

   bashCopy

   mkdir -p ~/.ssh && chmod 700 ~/.ssh
   ssh-keygen -t ed25519 -C "storify-server" -f ~/.ssh/id_ed25519 -N ""
   cat ~/.ssh/id_ed25519.pub

   2. Download the code into ~/app

   bashCopy

   git clone git@github.com:YOUR-USERNAME/storify.git ~/app
   ls -a ~/app

   No repository yet? Before You Install shows how to create one with GitHub Desktop. Or use the next step to upload the files instead.

   Check: ls -a ~/app lists package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .pnpmfile.cjs and .env.example.

8. 8

   Or upload the files from your computer

   Use this if your code is not on GitHub. Upload the contents of the app folder (the one with package.json) to /home/storify/app. Never upload node_modules, .next or .env.

   1. 1Show hidden files first: Windows Explorer → View → Show → Hidden items; macOS Finder → Cmd+Shift+. (full stop). Files such as .pnpmfile.cjs and pnpm-workspace.yaml must be uploaded too.
   2. 2macOS, Linux, or Windows with WSL: open a terminal in the app folder on your computer and run the command below.
   3. 3Windows without WSL: install WinSCP (free). Log in with File protocol SFTP, your server IP as Host name, port 22, user name storify and its password. Press Ctrl+Alt+H in WinSCP to show hidden files.
   4. 4In WinSCP, create the folder /home/storify/app on the server side and open it. Select everything in your app folder except node_modules, .next and .env, and drag it in.

   Run on your computer, inside the app folder

   bashCopy

   rsync -av --exclude .env --exclude node_modules --exclude .next ./ storify@SERVER-IP:/home/storify/app/

   If pnpm-workspace.yaml or .pnpmfile.cjs is missing, the install stops with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH. Upload the missing files and install again.

   Check: On the server, ls -a ~/app lists package.json, pnpm-workspace.yaml, .pnpmfile.cjs and .env.example.

9. 9

   Write the .env file

   The .env file holds the store's settings and secrets. Write it from the block below, with your production values from Before You Install. Do not copy .env.example as it is: its placeholder values count as real values.

   1. 1Run cd ~/app && nano .env. The editor opens an empty file.
   2. 2Paste the block below. Then change the values as described here.
   3. 3MONGODB_URI: your Atlas string, or the second block if MongoDB runs in Docker on this server.
   4. 4BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL: exactly the address people will open, with https:// and no / at the end.
   5. 5BETTER_AUTH_SECRET and CRON_SECRET: your two secrets. No secrets yet? Run node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" here on the server, once for each. Each run prints a new 64-character value.
   6. 6The two BUILD_ lines keep the build within a 4 GB server's memory. On a server with 8 GB of RAM or more, you may delete them.
   7. 7Save (Ctrl+O, Enter, Ctrl+X). Then run chmod 600 .env so only the storify user can read the file.

   .env

   bashCopy

   MONGODB_URI=mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify?retryWrites=true&w=majority
   MONGODB_DB_NAME=storify
   BETTER_AUTH_SECRET=<64 characters from the secret command>
   BETTER_AUTH_URL=https://shop.your-domain.com
   NEXT_PUBLIC_APP_URL=https://shop.your-domain.com
   CRON_SECRET=<a different 64 characters>
   BUILD_MAX_CPUS=2
   BUILD_TURBOPACK_MEMORY_MB=3072

   First line instead, when MongoDB runs in Docker on this server

   bashCopy

   MONGODB_URI=mongodb://storify:CHANGE-THIS-PASSWORD@127.0.0.1:27017/storify?authSource=admin

   Special characters in the MongoDB password break the connection string. Replace them: @ → %40, : → %3A, / → %2F, # → %23, ? → %3F. Or use a password with letters and digits only.

   Check: cat .env shows your lines. No < or > is left, there are no spaces around =, and MONGODB_DB_NAME=storify is there.

10. 10

    Install and build Storify

    pnpm install downloads the packages and pnpm build compiles the store. The build takes several minutes. Run cd ~/app && pnpm -v on its own first: the first time, Corepack asks ? Do you want to continue? [Y/n] before it downloads pnpm 10.24.0. Press Enter, check that it prints 10.24.0, then paste the block.

    bashCopy

    cd ~/app
    pnpm -v
    pnpm install --frozen-lockfile
    pnpm build

    Lines such as MongoDB connection error … ENOTFOUND or [sitemap] … emitting hub pages only mean the build could not reach the database. The build still finishes and these lines are harmless, but check MONGODB_URI before you start the store. If the build stops with JavaScript heap out of memory, check that swap is on (free -h) and build again.

    Check: pnpm -v prints 10.24.0. The build prints ✓ Compiled successfully and ends with a long table of routes that starts with Route (app). A failed build ends with ELIFECYCLE Command failed instead.

11. 11

    Run Storify as a service

    systemd starts Storify when the server boots and restarts it if it crashes. Block 1 writes the service file and fills in the path to your Node.js version by itself, so there is nothing to edit.

    1. 1Run sudo -v, then paste block 1 (as the storify user). Its last line prints the start command it wrote.
    2. 2Paste block 2 to start the service and test it.

    1. Write /etc/systemd/system/storify.service

    bashCopy

    NODE_BIN=$(dirname "$(which node)")
    sudo tee /etc/systemd/system/storify.service > /dev/null <<EOF
    [Unit]
    Description=Storify
    After=network.target
    
    [Service]
    Type=simple
    User=storify
    WorkingDirectory=/home/storify/app
    Environment=NODE_ENV=production
    Environment=PATH=$NODE_BIN:/usr/local/bin:/usr/bin:/bin
    ExecStart=$NODE_BIN/pnpm start -H 127.0.0.1 -p 3000
    Restart=always
    RestartSec=5
    
    [Install]
    WantedBy=multi-user.target
    EOF
    grep ExecStart /etc/systemd/system/storify.service

    2. Start and test

    bashCopy

    sudo systemctl daemon-reload
    sudo systemctl enable --now storify
    sleep 10
    systemctl status storify --no-pager
    curl -I http://127.0.0.1:3000

    status=127 or node: No such file or directory in sudo journalctl -u storify -n 50 --no-pager means the Node.js path is wrong: run block 1 again as storify, then sudo systemctl daemon-reload && sudo systemctl restart storify. Do the same if you later install another Node.js version with nvm. No 307? The store probably cannot reach MongoDB: check MONGODB_URI and the Atlas IP Access List, then sudo systemctl restart storify.

    Check: Block 1 prints a line like ExecStart=/home/storify/.nvm/versions/node/v24.…/bin/pnpm start -H 127.0.0.1 -p 3000. systemctl status shows active (running), and curl -I prints HTTP/1.1 307 Temporary Redirect with a location line that ends in /install.

12. 12

    Install Caddy for HTTPS

    Caddy receives visitors on ports 80 and 443, gets a free Let's Encrypt certificate for your domain by itself, renews it, and passes each request on to Storify. It needs the A record from the first step.

    1. 1Run sudo -v, then paste block 1. These are the commands from Caddy's install guide.
    2. 2In block 2, change shop.your-domain.com to your store's domain, then paste it. It replaces Caddy's example configuration.
    3. 3Paste block 3 to load the new configuration.

    1. Install Caddy

    bashCopy

    sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
    curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
    sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
    sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
    sudo apt update
    sudo apt install -y caddy

    2. Write /etc/caddy/Caddyfile

    bashCopy

    sudo tee /etc/caddy/Caddyfile > /dev/null <<'EOF'
    shop.your-domain.com {
        reverse_proxy 127.0.0.1:3000
    }
    EOF

    3. Load it

    bashCopy

    sudo systemctl reload caddy
    systemctl status caddy --no-pager

    No padlock after a few minutes? Run sudo journalctl -u caddy --no-pager | tail -n 30 to see why. The usual causes: the A record does not point at this server yet, port 80 is closed in a firewall, or Cloudflare's proxy is on.

    Check: https://shop.your-domain.com opens in your browser with a padlock and lands on /install.

13. 13

    Run the installer

    Open your store and finish the five installer screens right away: the first person who opens the installer becomes the owner. Every screen is explained in First Run & Installer.

    1. 1Open https://shop.your-domain.com. It redirects to /install.
    2. 2System check: every row should be green. An Application URL warning means the address in .env differs from the one in your browser. Correct both URL lines in ~/app/.env, run cd ~/app && pnpm build && sudo systemctl restart storify, then reload the installer page.
    3. 3Create your admin account. It becomes the protected Owner.
    4. 4Store basics: store name, default language, currency, and whether this is a multi-vendor marketplace.
    5. 5Where media is stored: enter your bucket details, or tick "Set storage up later" (nothing can be uploaded until you finish it in Admin → Settings → Storage). Buckets, CORS and self-hosted MinIO: Storage & Media.
    6. 6Choose your storefront template and click Install. Then click Go to sign in.

    Do not run pnpm create-admin or pnpm db:seed before this. Both create an admin, and from then on /install answers 404 for good.

    Check: The installer says "Your store is ready". After you sign in at /login, /admin opens the dashboard.

14. 14

    Schedule the 14 background jobs

    A cron job is a task the server runs on a timer. Storify needs 14 of them: they retry failed emails, hand orders to carriers, expire unfinished checkouts and more (Scheduled Jobs). On a VPS you add them to the storify user's crontab (its list of timed commands).

    1. 1Run grep CRON_SECRET ~/app/.env and copy the value after =.
    2. 2Run crontab -e. If it asks you to choose an editor, type 1 (nano) and press Enter.
    3. 3Paste the block below at the end of the file. Put your value in place of YOUR-CRON-SECRET and your store address in the BASE= line. Save.
    4. 4Test one job now: curl -H "Authorization: Bearer YOUR-CRON-SECRET" https://shop.your-domain.com/api/cron/email-deliveries. The answer starts with {"success":true.

    crontab -e

    bashCopy

    CRON_SECRET=YOUR-CRON-SECRET
    BASE=https://shop.your-domain.com
    * * * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/messaging-outbox > /dev/null
    * * * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/carrier-shipments > /dev/null
    */5 * * * *  curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/email-deliveries > /dev/null
    */5 * * * *  curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/messaging-escalations > /dev/null
    */5 * * * *  curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/boosts > /dev/null
    */15 * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/orange-money-reconcile > /dev/null
    */15 * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/mtn-momo-reconcile > /dev/null
    */15 * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/abandoned-checkouts > /dev/null
    */30 * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/carrier-tracking > /dev/null
    */30 * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/checkout-expiry > /dev/null
    0 * * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/vendor-subscriptions > /dev/null
    40 * * * *   curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/gateway-disputes > /dev/null
    0 3 * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/finance > /dev/null
    0 4 * * *    curl -fsS -H "Authorization: Bearer $CRON_SECRET" $BASE/api/cron/preorders > /dev/null

    Your first visit to the dashboard shows a "Background jobs have stopped" notice: the jobs had not run yet, so this is expected. After an hour, a new notice should name at most vendor-subscriptions, gateway-disputes, finance and preorders; after a day, none. If messaging-outbox or carrier-shipments are still named after an hour, the crontab is not running. Details: Scheduled Jobs.

    Check: crontab -l lists the two settings lines and all 14 job lines.

15. 15

    Back up the database

    Set this up before real orders arrive. With MongoDB in Docker, block 1 makes a backup now and block 2 makes one every night. With Atlas, the Free tier has no backups: for a live store, use a paid tier and turn on its backups.

    1. 1Docker: in block 1, put your MongoDB password in place of CHANGE-THIS-PASSWORD, run sudo -v, then paste it. It writes a file such as ~/backups/storify-2026-01-31.gz.
    2. 2For the nightly backup, run sudo crontab -e (the root user's crontab) and paste block 2 at the end, with your password in it. It backs up at 02:00 and deletes backups older than 14 days.
    3. 3Now and then, download a backup file to your computer (with WinSCP, or by running scp storify@SERVER-IP:backups/FILE-NAME . on your computer). A backup that only lives on the server is lost with the server.

    1. Back up now (MongoDB in Docker)

    bashCopy

    mkdir -p ~/backups
    sudo docker exec storify-mongo mongodump --uri="mongodb://storify:CHANGE-THIS-PASSWORD@127.0.0.1:27017/storify?authSource=admin" --archive --gzip > ~/backups/storify-$(date +%F).gz
    ls -lh ~/backups

    2. sudo crontab -e (every night)

    bashCopy

    0 2 * * *  docker exec storify-mongo mongodump --uri="mongodb://storify:CHANGE-THIS-PASSWORD@127.0.0.1:27017/storify?authSource=admin" --archive --gzip > /home/storify/backups/storify-$(date +\%F).gz
    30 2 * * * find /home/storify/backups -name 'storify-*.gz' -mtime +14 -delete

    To restore a backup (this replaces the current data): sudo docker exec -i storify-mongo mongorestore --uri="mongodb://storify:CHANGE-THIS-PASSWORD@127.0.0.1:27017/?authSource=admin" --archive --gzip --drop < ~/backups/FILE-NAME.gz

    Check: ls -lh ~/backups lists a storify-….gz file larger than 0 bytes. The next morning there is a new one.

16. 16

    Update to a new release later

    Read Updates & Migrations for every release you skip. Back up the database first. Then bring in the new files, build, restart and run that release's migrations. The store may show errors while the build runs, so choose a quiet time.

    1. 1With Git: on your computer, show hidden files, delete everything in your repository folder except the hidden .git folder, copy in everything from the new release's app folder (hidden files included), apply your own code changes again if you made any, then commit and push. On the server, run cd ~/app && git pull.
    2. 2Without Git: upload the new files the same way as before. With rsync, add --delete after -av, so files that the new release removed are removed on the server too. Your .env is never uploaded, so the server keeps its settings.
    3. 3Run sudo -v, then paste block 1 to install, build and restart.
    4. 4Run only the migrations that Updates & Migrations lists for the releases you skipped (block 2).

    1. Install, build and restart

    bashCopy

    cd ~/app
    pnpm install --frozen-lockfile
    pnpm build
    sudo systemctl restart storify

    2. Migrate

    bashCopy

    cd ~/app
    pnpm db:migrate --list
    pnpm db:migrate MIGRATION-NAME --dry-run
    pnpm db:migrate MIGRATION-NAME

    Check: systemctl status storify --no-pager shows active (running), and the store opens normally.

The first time you open a new Storify store, every page sends you to the installer at /install. In five screens it checks your setup, creates your admin account, saves the store basics, connects media storage and publishes a storefront template. Then it locks itself. This chapter is the same for every path: your computer, Dokploy, Vercel or a VPS.

1. 1

   Open your store's address

   Open the address people will use for your store. Until the install is done, every page sends you to /install.

   1. 1Your computer: http://localhost:3000.
   2. 2Vercel: your production address, the one in NEXT_PUBLIC_APP_URL, for example https://<project-name>.vercel.app. Do not use a preview or per-deployment address (the longer .vercel.app addresses with random letters): sign-in fails there with "Invalid origin".
   3. 3Dokploy or VPS: your store domain, for example https://shop.your-domain.com.

   Not sent to /install? An error page, or a page that loads for a long time and then fails, means the store cannot reach its database. Pages do not redirect then. Add /install to the address yourself to see which check fails. If the storefront opens, or /install shows 404, the store already has an admin: see "Locked out, or /install shows 404" below.

   Check: The address ends in /install, and the page says "Set up your store" with "System check" below it.

2. 2

   Pass the system check

   The first screen, "System check", tests four things. The first three block the install until they pass. Application URL is only a warning, but fix it before you continue.

   1. 1Node.js (the row shows your version): needs 22.12 or newer. On your computer or a VPS, install Node.js 24 LTS. On Dokploy, set NIXPACKS_NODE_VERSION=24. Vercel uses Node.js 24 by itself.
   2. 2MongoDB connection: check MONGODB_URI and MONGODB_DB_NAME=storify. Special characters in the database password must be encoded (for example @ as %40). The database must also accept connections from this server: see the Atlas IP Access List in "Create the MongoDB database" in Before You Install. While this row fails, the other rows say "Not checked — the installer could not reach its database".
   3. 3Authentication secret: BETTER_AUTH_SECRET must exist, have at least 32 characters, and not be an example value. Make a new one with the command below, and use exactly the name BETTER_AUTH_SECRET.
   4. 4Application URL: NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL must both equal the address in your browser, with the same http or https and no / at the end. If they differ, signing in fails with "Invalid origin".
   5. 5A green tick means the row passed. A yellow warning triangle means it needs a fix.
   6. 6Change the value as the table "How to fix a failed check on each platform" (above the steps) shows. Then click Check again. That button appears only while a blocking row fails; otherwise reload the page.

   Make a new secret (Windows, macOS and Linux)

   bashCopy

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

   The message under the rows says "restart the app after editing .env". On Vercel and Dokploy there is no .env file: change the value in the hosting panel instead, as the table shows.

   Check: All four rows show a green tick, and Continue is enabled.

3. 3

   Create your admin account

   This account becomes the store's Owner. The Team page protects it: no other administrator can demote, suspend or remove it.

   Your name

   Your full name.

   Email

   An address you can read. Password-reset emails go there once Email / SMTP is set up.

   Password

   At least 8 characters; the rule is shown under the field. Save it in a password manager.

   Check: Continue becomes clickable once the name, a valid email and a password of 8 or more characters are filled in.

4. 4

   Fill in the store basics

   These settings shape your shop. You can change every one of them later in Admin → Settings.

   Store name

   Required. The name your customers see.

   Default language

   The language your store opens in. English by default; search the list for another.

   Currency

   USD by default; search the list for your currency.

   Multi-vendor marketplace

   Ticked by default: other sellers can open their own stores. Untick it if only you will sell.

   Point of sale

   Off by default. Tick it to sell in person at a counter.

   Check: Continue becomes clickable once the store name is filled in.

5. 5

   Connect your media storage (or skip it)

   The screen "Where media is stored" connects the bucket that holds product images, videos and downloads. Where to find each value: Storage & Media.

   1. 1Click your provider: Cloudflare R2 (selected by default), AWS S3, MinIO or DigitalOcean Spaces. The form then shows only that provider's fields (listed below).
   2. 2Fill in the fields and click Test connection. It uploads a small test file and reads it back through the Public URL.
   3. 3Does the test say that no Public URL is set, or that the public URL is not accessible? Make the bucket publicly readable (for R2: turn on the r2.dev subdomain or connect your own domain). Paste that address into Public URL and test again.
   4. 4No bucket yet? Tick "Set storage up later". The install still finishes, but uploads stay unavailable until you add the bucket in Admin → Settings → Storage.
   5. 5Click Continue.

   Account ID

   Cloudflare R2 only. Your 32-character Cloudflare account ID.

   Region

   AWS S3, for example us-east-1. Optional for MinIO.

   Datacenter region

   DigitalOcean Spaces only, for example nyc3.

   Endpoint URL

   MinIO only, for example https://minio.example.com.

   Bucket name

   Every provider.

   Access key ID

   Every provider.

   Secret access key

   Every provider.

   Public URL

   Optional on this screen, but without it images do not show in browsers. For R2: the https://pub-….r2.dev address or your own domain.

   Is "Set storage up later" already ticked, with the message "Storage credentials were found in your .env file"? Then STORAGE_* values are set in your environment, and the store uses them. The placeholders from .env.example also cause this. If they are not your real keys, or you use a provider other than Cloudflare R2, untick the box and fill in the form: values saved here take priority.

   Check: Next to Test connection you see a green message such as "Cloudflare R2 connected and public URL verified".

6. 6

   Choose your storefront template

   Pick the design your storefront starts with. You can switch at any time later in Admin → Online Store → Themes, without losing products, orders or settings.

   1. 1Click a template card: Electronics (selected by default), Fashion or Classic Marketplace.
   2. 2Leave "Import this … template's demo store data" ticked to start with that template's sample catalog, collections and storefront. It creates no demo logins and no orders.
   3. 3Untick it to start with an empty store.

   The demo products' photos are not copied to your bucket: they load from Storify's public demo storage. Use the demo data to try Storify. For a real store, untick the box, or replace the sample products before launch.

   Check: The card you picked has a highlighted border, and the checkbox names the same template.

7. 7

   Click Install, then sign in

   Install creates everything in one go and then locks the installer. With demo data it can take a little while.

   1. 1Click Install and wait. Do not close the page.
   2. 2"Your store is ready" appears. Lines with a yellow warning sign under it are warnings, for example "The sample catalog could not be imported — you can import one from Products after signing in". The store is installed anyway; do what the warning says after you sign in.
   3. 3A red message instead, such as "Installation failed — please try again", means the install did not happen. Click Back to fix the screen the message points to, then click Install again. If the message is "Not found not found", the store is already installed: open /login.
   4. 4Click Go to sign in. The sign-in page opens at /login. Sign in with the email and password from the admin screen.

   Your first dashboard visit brings a notification titled "Background jobs have stopped". On a new store this is expected: no job has had its first run yet. Your path chapter shows how to schedule the jobs; on Vercel they run by themselves. On your own computer nothing runs them, so the notice stays, which is fine for a test store. On a server, the frequent jobs drop off the list within about an hour. finance and preorders run once a day, so they can stay on it for up to 24 hours. Scheduled Jobs explains each job.

   Check: You land on the admin dashboard, /admin opens it from now on, and /install now answers 404 (page not found).

8. 8

   Find your way around

   Add these paths to your store address, for example https://shop.your-domain.com/admin. Your default language has no prefix in the address. Other languages you turn on get one, for example /bn/products.

   Storefront

   /

   Sign in (every role)

   /login

   Admin panel

   /admin (opens the dashboard)

   Staff dashboard

   /staff

   Vendor dashboard

   /vendor/dashboard (only while Multi-vendor marketplace is on)

9. 9

   Instead of the installer (developers)

   These commands are for development and automated tests. Each one creates an admin, so the installer closes for good and its store, storage and template screens never run. Use the installer or these commands, not both.

   1. 1pnpm db:seed: a full demo store with catalog, orders, a published storefront and demo logins such as admin@storify.com / Admin@123. Run it on an empty database, before anyone opens the site. Other templates and error messages: "Optional: load the demo store instead of the installer" in Database Setup.
   2. 2pnpm db:seed:users: only the four demo logins: admin@storify.com, vendor@storify.com, staff@storify.com and customer@storify.com.
   3. 3pnpm create-admin: only your own admin, with no catalog and no template. Set those up in the admin afterwards. Always type the password: without it, the command uses ADMIN_PASSWORD from .env, which is change-me in .env.example.

   Your own admin only

   bashCopy

   pnpm create-admin you@shop.com "StrongPassword" "Your Name"

   Full demo store

   bashCopy

   pnpm db:seed

   Demo logins only

   bashCopy

   pnpm db:seed:users

   The demo passwords are public. Change every one before anyone else can reach the store. Never run pnpm db:seed, pnpm db:reset or pnpm db:full-reset against a live store's database.

   Check: The command ends without an error. pnpm create-admin prints Successfully created and upgraded … to Admin., and pnpm db:seed ends with a Demo Credentials: list.

10. 10

    Locked out, or /install shows 404

    /install answers 404 once the store has an admin. That is the lock, not a fault: sign in at /login instead. Forgot the password? Click "Forgot password?" on the sign-in page (needs Email / SMTP), or reset it with pnpm create-admin. The command sets the new password, re-activates the account, makes it an admin and signs it out everywhere.

    1. 1Your computer, or a VPS after you connect with SSH: run the command in a terminal in the app folder (the one with .env). On your computer, pnpm dev can keep running.
    2. 2Dokploy: open the application → General → Open Terminal → pick the container → Bash. Run the two lines from the Dokploy box below. If it says pnpm: command not found, type bash -l, press Enter and run them again.
    3. 3Vercel has no terminal: run the command from your computer, as "Run maintenance commands from your computer" in Deploy to Vercel shows.
    4. 4Sign in at /login with the new password.
    5. 5Only on a test database you can throw away: to see the installer again, run pnpm db:reset in the app folder on your computer. It deletes every product, order, account and setting in the database named in .env, without asking, so first check that .env points at the test database. Then stop pnpm dev with Ctrl+C, start it again and open /install. Or put a new, empty database name in .env instead (in both MONGODB_URI and MONGODB_DB_NAME) and restart.

    Your computer or a VPS

    bashCopy

    pnpm create-admin you@shop.com "NewStrongPassword"

    Dokploy terminal

    bashCopy

    cd /app && touch .env
    pnpm create-admin you@shop.com "NewStrongPassword"

    Always type the password in the command. Without it, the command uses ADMIN_PASSWORD from your environment, which is change-me if that line came from .env.example. Use a long password of letters and digits: characters such as $, !, quotes or spaces can change on the way through the terminal. Change it after you sign in.

    Check: The terminal prints Successfully upgraded … to Admin. and then Password updated.

The installer is done and your store is running. Work through this list once, in order, before you share the address with anyone. Every step ends with a check, so you know it worked. Only trying Storify on your own computer? Do the steps for sign-in, storage and email, use http://localhost:3000 wherever this chapter says https://your-domain, and skip the rest.

1. 1

   Sign in as the owner

   Sign in with the email and password you entered in the installer. This account is the store Owner: no other administrator can demote, suspend or remove it.

   1. 1Open https://your-domain/login.
   2. 2Enter the admin email and password from the installer and sign in. You land on the admin dashboard. Later you can always reach it at https://your-domain/admin.
   3. 3In the admin menu, open Team. Your account is in the list with the label Owner.
   4. 4Password not accepted? Click Forgot password? (this needs email, so it may not work yet), or follow "Locked out, or /install shows 404" in First Run & Installer.

   Your first visit to the dashboard creates a notification titled "Background jobs have stopped". On a new store this is expected: every job counts as not running until its first run. The step "Check that the background jobs run" below shows how to confirm that they start.

   Check: The dashboard opens at /admin/dashboard, and Admin → Team shows your account marked Owner.

2. 2

   Confirm the final address and HTTPS

   Sign-in, emails, payment providers and search engines all use one address: the one in your two URL variables. Make it final now, before you set up anything that uses it.

   1. 1Is the store still on a temporary address, such as https://<project-name>.vercel.app or a Dokploy sslip.io test address? Move it to your own domain first with Custom Domain & SSL.
   2. 2Check that BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL are both exactly https://your-domain (https, no / at the end). Vercel: Settings → Environment Variables. Dokploy: the Environment tab. VPS: the .env file.
   3. 3If you changed either value, rebuild, because NEXT_PUBLIC_APP_URL is fixed into the app when it is built. Vercel: Deployments → ⋯ → Redeploy, with "Use existing Build Cache" unticked. Dokploy: Environment tab → Save → Deploy. Dokploy Path B (prebuilt image): also change the NEXT_PUBLIC_APP_URL repository variable on GitHub, run Actions → Deploy image → Run workflow, wait for the green check, then click Deploy in Dokploy. VPS: run pnpm build, then sudo systemctl restart storify.
   4. 4Open https://your-domain/robots.txt in your browser. It shows the address the app was built with.
   5. 5Sign out, then sign in again at https://your-domain/login.

   Open and sign in to the store only on the address in these variables. On any other address (an old domain, a *.vercel.app preview link, the server's IP address) sign-in fails with "Invalid origin".

   Check: The browser shows a padlock on https://your-domain, robots.txt contains the line Sitemap: https://your-domain/sitemap.xml, and you can sign in there.

3. 3

   Test the storage connection

   Product images, logos and downloads are kept in your storage bucket, not on the server. Test the connection now, before you add products.

   1. 1Open Admin → Settings → Storage (https://your-domain/admin/settings/storage).
   2. 2If you ticked "Set storage up later" in the installer, choose your provider and fill in the bucket details now. Storage & Media shows where to find each value.
   3. 3Click Test Connection, then save. The test uploads a small file and reads it back through the Public URL.
   4. 4Open your bucket's CORS rule (you added it in Before You Install, step "Create a storage bucket"). It must list https://your-domain exactly. CORS is the bucket setting that lets your website send files straight to the bucket.
   5. 5Open a product in Admin → Products (or create one), add an image and save. Then open that product on the storefront.

   Without the right CORS rule, the browser cannot send files straight to the bucket, so they go through your server instead. Large files then fail with "File is too large to upload through the server" (on Vercel, anything over 4.5 MB).

   Check: The test reports "… connected and public URL verified" (for example "Cloudflare R2 connected and public URL verified"), and the new image shows on the storefront.

4. 4

   Set up email and send a test

   Password resets, team invites and order emails need a working mail server (SMTP). Without it, nobody can reset a forgotten password.

   1. 1Open Admin → Settings → Email Configuration (SMTP) (https://your-domain/admin/settings/email).
   2. 2Turn on Enable SMTP Email.
   3. 3Fill in SMTP Host, SMTP Port, SMTP Username, SMTP Password, From Email and From Name with the values from your email provider. For port 465, also turn on Use SSL/TLS. Email / SMTP lists common providers.
   4. 4Save the settings. The test uses the saved values.
   5. 5Under Test Email, type your own address and click Send Test Email. Then open your inbox, and look in the spam folder too.

   On a VPS or Dokploy server, a test that times out usually means your server provider blocks outgoing mail ports (DigitalOcean, for example, blocks 25, 465 and 587 on new servers). Use port 2525 if your email provider offers it, or ask the provider to unblock SMTP. If the test email lands in spam, set up SPF, DKIM and DMARC for your sender domain. Your email provider's dashboard shows the DNS records to add.

   Check: A message that starts with "Test email sent successfully" appears, and the test email arrives in your inbox.

5. 5

   Check that the background jobs run

   Storify has 14 background jobs. A background job (cron job) is a task the platform runs on a timer: it retries failed emails, hands paid orders to the carrier, sends abandoned-checkout emails and checks payments. Vercel runs them for you. On Dokploy and a VPS you add them yourself, as shown in Scheduled Jobs.

   1. 1Vercel: open Settings → Cron Jobs. It lists 14 jobs. Click View Logs next to /api/cron/messaging-outbox.
   2. 2Dokploy: open the application's Schedules tab. It lists the 8 schedules from Scheduled Jobs. Click the play button (Run Manual Schedule) on storify-every-minute, then the list icon next to it to see the run.
   3. 3VPS: run crontab -l and check that it lists 14 job lines. Then call one job by hand as shown in Scheduled Jobs, step "Test one job by hand".
   4. 4External scheduler (for example cron-job.org): open the run history of each job.
   5. 5About an hour later, open the admin dashboard again and read the newest "Background jobs have stopped" notification, if there is one.

   A 401 (Unauthorized) means CRON_SECRET is missing or does not match. If messaging-outbox or carrier-shipments are still named after an hour, the schedule is not running: go back to your platform's part of Scheduled Jobs. The dashboard sends the notice only once for the same list of jobs, so check the logs, not only the notice.

   Check: The runs succeed: status 200 in Vercel's logs, messaging-outbox 200 in Dokploy's run log, a reply that starts with {"success":true from the hand test, or 200 in your scheduler's history. After an hour, a new "Background jobs have stopped" notice names at most vendor-subscriptions, gateway-disputes, finance and preorders. After a day it does not appear at all.

6. 6

   Point webhooks at the live domain

   A webhook is a message a payment or shipping service sends to your store, for example "this payment succeeded". Register only the services you use. Replace your-domain with your store's address.

   Stripe

   https://your-domain/api/payments/webhook. Choose the events listed in Payment Gateways, then paste the signing secret into Admin → Settings → Payment Settings.

   PayPal

   https://your-domain/api/payments/paypal/webhook. Then paste the webhook ID into Payment Settings.

   Paystack

   https://your-domain/api/payments/paystack/webhook

   Razorpay

   https://your-domain/api/payments/razorpay/webhook. Then paste the webhook secret into Payment Settings.

   Pesapal

   Nothing to type. Click Register IPN in Admin → Settings → Payment Settings. It needs NEXT_PUBLIC_APP_URL to be a public https:// address.

   Meta (WhatsApp, Messenger, Instagram)

   https://your-domain/api/webhooks/meta, with the value of META_WEBHOOK_VERIFY_TOKEN as the verify token. See Omnichannel Messaging.

   Telegram

   On Vercel, nothing to type: Storify registers the webhook when you connect the bot (it needs https://). On Dokploy or a VPS, the current release may register the server's internal address (https://localhost:3000/… or https://127.0.0.1:3000/…) instead of your domain, and Telegram refuses that, so connecting the bot can fail there. Contact support before you rely on Telegram on those hosts.

   Shippo

   Click Generate webhook URL in Admin → Settings → Shipping & Delivery, then paste that URL into Shippo.

   Shiprocket

   https://your-domain/api/webhooks/carriers/shiprocket. As the token, use the same value as Webhook token (x-api-key) in Admin → Settings → Shipping & Delivery.

   Copy each path exactly, and use the same address as in NEXT_PUBLIC_APP_URL. On Vercel, never use a preview or per-deployment *.vercel.app link: those are behind Vercel's login, so every webhook gets 401. On Dokploy or a VPS, an admin screen may show a webhook address that starts with https://localhost:3000. Ignore it and type your real domain.

   Check: Each provider's webhook page shows your https://your-domain/… address. After your test order (below), the provider's delivery log shows a success (status 200).

7. 7

   Register the social sign-in addresses (only if you use them)

   Skip this step if customers sign in with email and password only. Google and Facebook send people back to your store after sign-in, but only to an address you registered with them.

   1. 1Open Admin → Settings → OAuth / Social Login and turn on Google Sign-In or Facebook Sign-In.
   2. 2Open "How to set this up (step by step)" under the provider. It lists the steps in the provider's console, and shows the address to register with a Copy button.
   3. 3Google: add https://your-domain/api/auth/callback/google under Authorized redirect URIs in your Google Cloud OAuth client.
   4. 4Facebook: add https://your-domain/api/auth/callback/facebook under Valid OAuth Redirect URIs (Facebook Login → Settings in your Meta app).
   5. 5Back in Storify, paste the Google Client ID and Client Secret (Facebook: App ID and App Secret), save, then click Verify credentials.
   6. 6Sign out, open https://your-domain/login and click Continue with Google (or Continue with Facebook).

   Storify builds these addresses from BETTER_AUTH_URL. If you change the domain later, register the new addresses at Google and Meta too.

   Check: You come back to the store, signed in.

8. 8

   Place one real test order

   A real order proves that payment, webhooks, email and stock work together. Use a cheap product and a real card, then refund the order.

   1. 1Open the storefront in a private browser window, add a product to the cart and check out as a customer, with an email address you can read.
   2. 2Pay with a real card or wallet. If you like, try the gateway's test mode first, then repeat in live mode.
   3. 3In Admin → Orders, open the new order.
   4. 4If you offer refunds, refund the order from its page.

   If the payment succeeds but the order stays pending, the gateway's webhook is not arriving: check it against "Point webhooks at the live domain" above, and see Troubleshooting.

   Check: The order shows the payment status Paid, the order confirmation email arrives, and after the refund the payment status changes to Refunded.

9. 9

   Turn off demo mode and remove demo logins

   Demo mode blocks deletes and settings changes. The demo accounts that pnpm db:seed and pnpm db:seed:users create have passwords anyone can look up. Neither belongs on a live store.

   1. 1In your environment variables, delete DEMO_MODE and NEXT_PUBLIC_DEMO_MODE, or set them to false. Also delete ADMIN_PASSWORD if it is there.
   2. 2Rebuild as in "Confirm the final address and HTTPS" above, because NEXT_PUBLIC_DEMO_MODE is fixed into the app when it is built.
   3. 3Only if you ran pnpm db:seed or pnpm db:seed:users: sign in as admin@storify.com and change its password in your admin profile. If Admin → Team marks this account as Owner, it cannot be removed, so give it a strong password.
   4. 4Change the passwords of the other demo accounts, or suspend or remove them: vendor@storify.com, staff@storify.com, customer@storify.com and the …@example.com accounts.

   Check: /login shows no "Demo account login credentials" card, and signing in with admin@storify.com and Admin@123 fails.

10. 10

    Set up backups

    A backup is a copy of your data that you can restore after a mistake or a failure. Orders, customers and settings live in MongoDB. Images live in your storage bucket, not in the database backup.

    1. 1MongoDB Atlas: the Free tier (M0) has no backups. For a live store, move to a paid tier and turn on its backups (the exact labels may differ slightly).
    2. 2Dokploy MongoDB service: set up the Backups tab as shown in Deploy with Dokploy, step "Back up the database". Then click Run Manual Backup once.
    3. 3Atlas or your own server: you can also run mongodump on a schedule. It is part of the free MongoDB Database Tools. Use the command below with your own connection string.
    4. 4Save every environment value (secrets, keys, URLs) in your password manager. Vercel Secret values cannot be read back later.

    Manual backup with mongodump (put your own connection string in the quotes)

    bashCopy

    mongodump --uri="mongodb+srv://USER:PASSWORD@cluster0.xxxxx.mongodb.net/storify" --archive=storify-backup.gz --gzip

    To restore a mongodump file, run mongorestore with --archive=storify-backup.gz --gzip and the --uri of the database to restore into. Practise once on a test database, so you know it works before you need it.

    Check: Dokploy: after Run Manual Backup, a new file appears in your backup bucket. Atlas: within a day, your cluster's backup page lists a snapshot. mongodump: the file storify-backup.gz exists and is not empty.

11. 11

    Do a security pass

    Go through Security & Hardening once before launch. The most important items are below.

    1. 1Admin → Settings → Security & Access Control: set the password policy.
    2. 2Admin → Settings → Two-Factor Authentication: turn on Enable Two-Factor Authentication and Enable for Administrators, save, then set up two-factor sign-in on your own account.
    3. 3Keep your GitHub repository private, and never commit .env.
    4. 4Make sure payment keys and webhooks are in live mode, not test mode.
    5. 5Give every person their own account (Admin & Roles). Never share the Owner login.

    Check: You can tick off every item on the Security & Hardening page.

12. 12

    Configure the rest of your store

    Your store is ready for customers. Settings Reference lists every setting and where to find it. Most stores set these up next:

    1. 1Payments: Payment Gateways.
    2. 2Shipping: Shipping Carriers.
    3. 3Look and feel: Branding & Theme.
    4. 4Languages: Multi-language.
    5. 5Your team: Admin & Roles.

Storify has 14 background jobs. A background job (a cron job) is a task that runs on a timer, for example every minute or once a day. The jobs retry emails and messages that failed, hand paid orders to carriers, expire unfinished checkouts, check mobile-money payments and more. If they stop, the store still looks fine, but this work silently stops. Vercel runs them for you from the bundled vercel.json file (Pro plan). On Dokploy, a VPS or any other host, you schedule them yourself, once.