What's in the Box & Requirements
This edition supports one school with unlimited branches per installation. Customers may install it on Windows, Ubuntu, or Docker. For multi-school / SaaS licensing, contact the Kindie team.
📦 What's in the box
| Folder | What it is |
|---|
api/, config/, views/ | Sails.js (Node.js) backend + REST API |
react-backend/ | Web Admin SPA source (React + Vite + TypeScript) |
assets/react-backend-dist/ | Pre-built Web Admin — served by the backend, no build needed |
docker-compose.yml, Dockerfile | One-command Docker deployment |
.env.example | All configuration, documented per variable |
v4-legacy/ | Previous generation (v4) for existing users — see "Upgrading from v4" |
⚙️ Requirements
- A computer, VPS, or server you control. Shared PHP hosting is not supported.
- Node.js 20.x and MongoDB 5.0+ for a manual installation.
- Docker + Docker Compose when using the Docker installation path.
- Redis is optional for one application instance, but required when several instances share sessions, cache, or realtime connections.
- An SMTP account is optional, but required for password-reset and system emails.
- A Firebase project is optional, but required for mobile push notifications.
Server sizing: the project does not currently have a load-tested CPU, RAM, or disk minimum. Docker limits the application container to 2 GB and Node.js to a 1536 MB heap; a host running MongoDB, Redis, and the application needs additional memory and disk space for uploads, database growth, and backups. Do not treat 2 GB as a production sizing recommendation for the whole stack.
The release package includes the pre-built Web Admin interface. Customers do not need to install or build the react-backend project unless they are customizing the source code.
Before You Begin
This installation is self-service — you (or your IT contact) run it yourself, on whichever environment you already have or prefer (Windows, Ubuntu, or Docker; every path is documented in full, no environment is more "official" than another). If you get stuck, the Kindie team is available to help — see "Contact & Support".
✅ Gather these before you start
| Item | Why you need it |
|---|
| Your Envato purchase code | The setup wizard asks for it (Envato → Downloads → License certificate & purchase code) |
| A computer, VPS, or server you already control | Where Kindie will run — see "What's in the Box & Requirements" for what it needs installed |
| Admin access to that machine | sudo on Linux, Administrator on Windows, or the ability to install Docker |
| A domain name (only if this will be a public website) | Needed for HTTPS — see "Production Deployment". Skip this if you're only trying Kindie out or running it on an internal office network. |
| An SMTP account (recommended) | Without it, password-reset and system emails cannot be sent |
| A Firebase account (only if you want mobile push notifications) | Free to create — see "Application Configuration" |
| The school's basic info | Name, logo, and the administrator account you want to create — the setup wizard asks for these directly |
🗺️ What happens next
Pick the page matching your environment — Windows Installation, Linux Installation, or Docker Quick Start — and follow it start to finish. Each one is self-contained: install the platform services it lists, then it hands off to "First Run" for the same setup wizard regardless of which path you took.
Windows Installation
Installing the platform services Kindie needs directly on a Windows computer or server, without Docker — this page installs Node.js, MongoDB, and (optionally) Redis one by one yourself. Prefer one command instead? Docker also runs on Windows — see "Docker Quick Start".
Requirements: Windows Server 2019 or 2022 for a real, public deployment (see "Production Deployment" for the domain/HTTPS steps). A regular Windows 10/11 PC also works, for trying Kindie out or running it as an internal office server only. See "What's in the Box & Requirements" for sizing notes — there is no official minimum RAM/disk figure yet, so plan generously and monitor usage.
🟢 Install Node.js
Step 1
- Go to
nodejs.org and download the 20.x LTS .msi installer for Windows — the app requires Node ^20.11.0.
Step 2
- Run the
.msi, click through the installer, and make sure "Add to PATH" is checked.
Step 3
- Verify from Command Prompt / PowerShell:
node --version # must print v20.x
npm --version
🍃 Install MongoDB
Step 1
- Download the
.msi installer from the MongoDB Download Center (Community Server, version 5.0–7.0).
Step 2
- Run the installer, choose Complete, and check "Install MongoDB as a Service".
🔎 Notes
- Install as a Service
- MongoDB starts automatically with Windows — no need to launch it by hand every time.
- MongoDB Compass
- An optional GUI to browse/edit the database directly — not required.
Do not create a Windows Firewall rule for port 27017 (MongoDB) or open it on your router. MongoDB only needs to be reachable from this same computer.
Step 3 (recommended): verify MongoDB is actually running
- The MongoDB installer offers to also install mongosh (the MongoDB Shell) — leave that checked. Open a new PowerShell window and run:
mongosh --eval "db.runCommand({ ping: 1 })"
- A reply containing
ok: 1 means MongoDB is up and reachable. If the command is not found, download mongosh separately from the MongoDB Download Center.
Step 4 (recommended): install the backup tools now
- Download MongoDB Database Tools (
mongodump/mongorestore) from the MongoDB Download Center and run its .msi installer — these are not included with the MongoDB server installer above, and you'll need them later (see "Backup & Restore").
🔴 Redis (optional)
Redis is optional when one Kindie application instance runs on the server. It is required when several instances share sessions, cache, or realtime connections. There is no officially maintained native Redis build for Windows; if you need Redis, run it inside WSL2 or a small Linux VM and point REDIS_URL at that instance.
📦 Install and start Kindie
Step 1
- Extract the release package to a permanent folder such as
C:\Kindie. Do not run it from a temporary Downloads folder.
Step 2
- Open PowerShell in the Kindie folder and install dependencies.
npm install
Step 3
- Start Kindie. On a new installation, the terminal prints a secure setup link.
npm start
Open the complete link, including ?token=.... Do not open only http://localhost:1337 during first setup.
Step 4
- Complete the browser wizard. It creates
.env, generates security keys, and opens the school setup screen.
🔥 Local network access (internal use only)
By default only this computer can open Kindie. If you only need other computers on the same office network to reach it — not a public domain — allow port 1337 through Windows Firewall, then share this computer's local IP address (find it with ipconfig, look for "IPv4 Address") — staff open http://THAT-IP:1337 in their browser.
New-NetFirewallRule -DisplayName "Kindie" -Direction Inbound -Protocol TCP -LocalPort 1337 -Action Allow
Run this in PowerShell as Administrator. For a real public website with a domain name and HTTPS, skip this and follow the Windows steps in "Production Deployment" instead.
Linux Installation (Ubuntu 22.04+)
Installing the platform services Kindie needs on an Ubuntu VPS over SSH, without Docker — this page installs Nginx, MongoDB, Node.js, and (optionally) Redis one by one yourself. Prefer one command instead? See "Docker Quick Start" — it runs on the same Ubuntu VPS.
Requirements: Ubuntu 22.04 LTS or 24.04 LTS. See "What's in the Box & Requirements" for sizing notes — there is no official minimum RAM/disk figure yet; MongoDB, logs, uploads, and backups all grow disk usage over time, so monitor and expand as needed.
🔑 Connect to your server
When you buy or rent a VPS, the hosting provider emails (or shows in their dashboard) three things: a public IP address, a username (usually root or ubuntu), and a password or private key file. Everything below is typed into a terminal connected to that server, not on your own computer.
🔎 How to open that terminal
- Windows
- Download PuTTY, open it, type the server's IP in "Host Name", click Open, then log in with the username/password from your provider.
- macOS / Linux
- Open the built-in Terminal app and run
ssh username@your-server-ip (e.g. ssh root@203.0.113.10), then enter the password when asked.
The first time you connect you'll see a warning about an unknown host key ("Are you sure you want to continue connecting?") — this is normal for a brand-new server; type yes to continue.
🔄 Update the system
sudo apt update
sudo apt upgrade -y
🌐 Install Nginx
sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx
Configuring the actual site (reverse proxy + SSL) is covered separately in "Production Deployment".
🍃 Install MongoDB 7.0
sudo apt-get install -y gnupg curl
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] \
https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org
sudo systemctl enable mongod
sudo systemctl start mongod
MongoDB listens only on 127.0.0.1 (this server) by default — leave it that way. Do not open port 27017 in the firewall in the "Production Deployment" section; only the web ports need to be public.
Verify MongoDB is actually running, using mongosh (the MongoDB Shell — usually installed automatically as part of mongodb-org above; if the command below says "not found", install it with sudo apt-get install -y mongodb-mongosh):
mongosh --eval "db.runCommand({ ping: 1 })"
A reply containing ok: 1 means MongoDB is up and reachable.
Also install the backup tools now, while you're here — they're a separate package from the server, and you'll need them later (see "Backup & Restore"):
sudo apt-get install -y mongodb-database-tools
🟢 Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
Do not use Node 16 — it's end-of-life, and some old Docker images still reference it. package.json requires Node ^20.11.0.
🔴 Install Redis (optional)
sudo apt-get install -y redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server
Optional when one Kindie instance runs on the server. Install it when several instances share sessions, cache, or realtime connections.
📦 Copy and start Kindie
Step 1
- Copy the release ZIP to the server and extract it into a permanent folder such as
/opt/kindie.
sudo mkdir -p /opt/kindie
sudo unzip kindie-single-*.zip -d /opt
sudo chown -R "$USER":"$USER" /opt/kindie
Step 2
- Install dependencies and start Kindie.
cd /opt/kindie
npm install
npm start
Open the complete setup link printed in the terminal, including ?token=....
Docker Quick Start
An installation option using Docker Compose. Estimated time: 10–20 minutes, mostly spent waiting for images to download.
🐋 Install Docker
Requires Docker Engine 24+ with the Compose plugin (the docker compose command, not the older separate docker-compose tool). Already have it? Verify with docker --version and docker compose version, then skip to "Unzip and start" below.
🪟 Windows / Mac: Docker Desktop
Step 2
- On Windows, the installer may prompt to enable WSL2 — accept it and restart the computer if asked. This is a one-time setup Docker Desktop needs.
Step 3
- Launch Docker Desktop from the Start menu and wait until it shows "Docker Desktop is running" (the whale icon in the system tray stops animating).
Step 4
- Verify from PowerShell / Terminal:
docker --version
docker compose version
🐧 Ubuntu: Docker Engine
Step 1: Set up Docker's repository
sudo apt-get update
sudo apt-get 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
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
Step 2: Install Docker Engine and the Compose plugin
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
Step 3 (optional): run Docker without typing sudo every time
sudo usermod -aG docker $USER
Log out and reconnect over SSH for this to take effect.
Step 4: Verify
docker --version
docker compose version
Docker doesn't mean "nothing to prepare" — two things are still on you:
- Node.js, MongoDB, and Redis — you don't install any of these. They run inside containers that Docker Compose creates automatically (Node is baked into the Kindie image; MongoDB and Redis each run in their own container).
- An SMTP account for outgoing email — Docker does not provide this. Create one with any provider (Mailgun, Gmail, your own mail server...) and enter it in the setup wizard, exactly like the Windows/Linux paths — this step is the same no matter how you install.
🗜️ Unzip and start
Step 1: Unzip and create two empty files
unzip kindie-single-*.zip && cd kindie-single-*
touch .env .install.lock && chmod 666 .env .install.lock
You do not need to fill in .env yourself — the setup wizard writes it for you in Step 3, including the security keys. These two files must already exist and be writable before you start the stack: the wizard runs inside the container, and without the mount, everything it writes would be lost the next time the container is recreated. In Windows PowerShell, use New-Item .env -ItemType File and New-Item .install.lock -ItemType File instead of touch.
Step 2: Start the stack
docker compose up -d
Step 3: Open the setup link
- Get the one-time setup link. It carries an access token, so nobody else who can reach the port can take over your installation before you do:
docker compose logs kindie | grep "token="
- It looks like
http://localhost:1337/?token=… — replace localhost with your server's address. Prefer to choose the token yourself? Set INSTALLER_TOKEN (16+ characters) in the environment: block of docker-compose.yml before starting the stack.
- Open that link — since the application has not been configured yet, it shows the setup wizard instead of the login screen.
🖼️[Screenshot placeholder — setup wizard, Requirements step]
The wizard walks you through Requirements → Licence (your Envato purchase code) → Database → Application (public address, SMTP, Redis) → Install, then creates your school. See "First Run" for what happens on that last part.
| Service | Port | Notes |
|---|
| Kindie application | 1337 (all interfaces) | Application and pre-built Web Admin interface |
| MongoDB | 27017 (127.0.0.1 only) | Data is stored in the Docker volume mongo-data. Reachable only from this same server (e.g. with MongoDB Compass over an SSH tunnel) — not from the Internet. |
| Redis | not published | Only reachable from the kindie container itself, over the internal Docker network |
Uploaded photos/files are stored in the Docker volume uploads — kept across restarts and updates, separate from the release folder.
MongoDB is protected automatically — the release package's docker-compose.yml only exposes it to this same server, not the Internet, and you don't need to configure anything for that. If you (or a developer working on your site) ever edit docker-compose.yml, keep the 127.0.0.1: part in front of MongoDB's port: without it, a regular firewall rule (ufw) is not enough to protect it, because Docker manages its own network rules separately. For production, also put HTTPS in front of port 1337 — see "Production Deployment" — rather than sharing the plain http://SERVER_IP:1337 address with families.
First Run
What happens once you open the setup link, and how to bring your data in. This is the Web Admin wizard — the same one whether you installed with Docker or manually.
🚀 Setting up your school
Step 1: School information
- Name, code, contact details, logo. This is the one school this licence runs; you can add as many branches as you like later.
Step 2: Administrator account
- The login you will use from now on. Keep it safe: it has full access, including finance and student records.
Step 3: System settings
- Language, date format, currency, notification defaults. Automatic sample data is off by default — turn it on only if you want a populated demo to explore. It creates demo teachers and parents with the password
123456: delete those accounts before you put real data on the system.
🖼️[Screenshot placeholder — setup wizard, System settings step]
Step 4: Academic session
- Your first school year. Click Finish and you land on the login screen — sign in with the administrator account you just created.
Once you finish the wizard, opening /installation again simply redirects to the login page — it does not run twice. To start over from the first step, delete .install.lock and .env, drop the database, and restart the application.
📋 Next steps
Import students & parents
- Go to People → Import, download the Excel template, fill it in, then upload.
- The template includes Height, Weight, Blood Group and Allergy columns — filling in Allergy is strongly recommended: the Daily Feed blocks meal actions that conflict with a child's recorded allergies.
Go live
- Create classes, assign teachers, and you're live. Share the mobile/PWA app with families (see "Mobile App Setup").
🎬 Video demo
A full walkthrough of the steps above, start to finish.
Application Configuration
How configuration actually gets into .env, and how to change it later.
📝 First install: use the wizard, not a text editor
.env is written for you by the setup wizard on first start (see "First Run") — you do not hand-edit .env.example yourself for a normal install, whether you're using Docker or running manually.
🔧 Changing configuration after install
To change a setting later (SMTP, Redis, mail sender, etc.), edit .env directly and restart the application — the wizard does not run again once .install.lock exists. .env.example documents every variable the application reads, one by one.
🤖 Unattended / scripted deploys
For CI or infrastructure-as-code setups where nobody opens a browser to run the wizard, set SKIP_INSTALLER=true and provide every required variable yourself (Docker secrets, Kubernetes secrets, CI variables...). The minimum for the app to start:
NODE_ENV=production
EDITION=single
SKIP_INSTALLER=true
BASE_URL=https://your-domain.com
MONGO_HOST=127.0.0.1
MONGO_DB_NAME=kindiedb1
TOKEN_SECRET=<48+ random characters>
SESSION_SECRET=<48+ random characters>
The app validates this at startup and tells you exactly what's missing, instead of failing silently.
🔥 Push notifications (Firebase)
This entire section is optional — skip it if you don't need mobile push notifications yet. The app starts fine without it.
Step 1: Create a Firebase project
- Go to the Firebase Console and sign in with any Google account.
- Click Add project, give it a name (e.g. your school's name), and finish the wizard. Cloud Messaging (push notifications) is included automatically — nothing extra to enable.
Step 2: Generate the service account key
- Inside the project, click the ⚙️ gear icon → Project settings → Service accounts tab.
- Click Generate new private key — this downloads a
.json file. Keep it safe; anyone with this file can send push notifications as your app.
Step 3: Add it to Kindie
- Open the downloaded
.json file in a text editor, copy its entire contents, and paste it as one line into FIREBASE_SERVICE_ACCOUNT_JSON in .env, then restart the application.
Without this variable the app still starts, but push notifications never fire — see "Troubleshooting". Never share this .json file or paste it into a support ticket/screenshot.
📧 Customer-created services
Configure only the services you use
- SMTP
- Create an SMTP account with your email provider. Without valid SMTP settings, password-reset and system emails will not be delivered. 📄 Download mail-smtp.env.example for a filled-in reference.
- Firebase
- Create a Firebase project and service account only when mobile push notifications are required. Firebase is not required for the application to start.
- Redis
- Use the Redis URL when running more than one Kindie application instance or when shared cache/session storage is required — otherwise leave it blank in the setup wizard and the app uses an in-memory cache. The Docker Compose stack always runs a Redis container regardless. Note:
.env.example's own sample value shows TYPE_CACHE=redis as an illustration of the Redis option — it is not a requirement, and the setup wizard writes the correct value for your actual choice.
- File storage
- Single-server installations can store files on the server disk. Back up uploads together with the database.
Never put real passwords, service-account JSON, or security keys in screenshots, support tickets, or public repositories.
Running the Application
Starting the app for development, and keeping it running in production.
▶️ Start or test the application
npm install
npm start
The default application port is 1337. Stop a foreground test run with Ctrl+C.
🔁 Production (keep it running)
Run Kindie under a process supervisor such as a Windows Service, systemd, or Docker Compose. The supervisor must restart the application after a server restart and keep the application folder and .env file unchanged.
Do not use sails lift or forever start as the normal customer deployment command. The release package is started with npm start.
Using Docker? You can skip the rest of this section — restart: unless-stopped in docker-compose.yml already keeps the application running and restarts it after a reboot, automatically.
🐧 Linux: systemd
Step 1
- Download the service file, edit the paths/user inside it to match your install, then save it as
/etc/systemd/system/kindie.service: 📄 Download kindie.service.example
Step 2
sudo systemctl daemon-reload
sudo systemctl enable kindie
sudo systemctl start kindie
sudo systemctl status kindie
🪟 Windows: run as a service (NSSM)
Windows has no built-in way to turn an arbitrary command into a service, so use the free tool NSSM (Non-Sucking Service Manager).
Step 1
- Download NSSM, extract it, and open PowerShell as Administrator in that folder.
Step 2
.\nssm.exe install Kindie
- A window opens — set Path to your Node.js install (e.g.
C:\Program Files\nodejs\node.exe), Startup directory to your Kindie folder (e.g. C:\Kindie), and Arguments to app.js. Click Install service.
Step 3
Start-Service Kindie
Kindie now starts automatically with Windows. Manage it from services.msc like any other Windows service.
📋 Viewing logs
| Environment | Command / location |
|---|
| Linux, systemd | sudo journalctl -u kindie -f (add --since "1 hour ago" to narrow it down) |
| Docker Compose | docker compose logs -f kindie |
| Windows, NSSM | By default NSSM doesn't capture output — set I/O → Output (stdout) to a file path in the NSSM install window (Step 2 above) to get a log file, or check Event Viewer → Windows Logs → Application. |
| Foreground test run (any OS) | Printed directly in the terminal where you ran npm start |
Production Deployment
Putting a real domain and HTTPS in front of the app — Nginx on Linux, or IIS on Windows.
Downloadable example config files on this page: nginx-kindie.conf.example (below) and web.config.example (below). Setting up outgoing email instead? See mail-smtp.env.example in "Application Configuration".
🌐 Linux: Nginx reverse proxy
Step 1: Point your domain at the server
- Find your server's public IP address — on the VPS, run
curl -4 ifconfig.me; or check your hosting provider's dashboard.
- Log in to wherever you bought/manage the domain (the registrar, or a DNS service such as Cloudflare), find the DNS or DNS records section, and add an A record: Host/Name
@ (or a subdomain like app), Type A, Value = your server's IP address.
DNS changes can take anywhere from a few minutes up to 24–48 hours to take effect everywhere. Check with
nslookup your-school.com (or
dnschecker.org) — once it returns your server's IP, move on to Step 2.
Step 2
- Create
/etc/nginx/sites-available/kindie.conf:
server {
server_name your-school.com;
client_max_body_size 20m;
location / {
proxy_pass http://127.0.0.1:1337;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
- Enable it:
ln -s /etc/nginx/sites-available/kindie.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
📄 Download nginx-kindie.conf.example — the same config as a ready-to-edit file.
Step 3
- Allow web ports in the firewall, while keeping ports 1337, 27017, and 6379 private.
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status
Step 4
- Get an SSL certificate — Let's Encrypt / Certbot is the simplest:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-school.com
The X-Forwarded-Proto header matters: the app trusts it in production to know it's being served over HTTPS — without it, secure cookies and links built from BASE_URL can misbehave.
🪟 Windows: IIS reverse proxy
Step 1: Install IIS and its extensions
- Enable IIS: Server Manager → Add roles and features → Web Server (IIS) (or on Windows 10/11: Turn Windows features on or off → Internet Information Services).
- Install two extra IIS modules — download and run each installer: Application Request Routing (ARR) and URL Rewrite.
Step 2: Turn on proxying
- Open IIS Manager, click the server name at the top of the tree, open Application Request Routing Cache → Server Proxy Settings..., check Enable proxy, then Apply. Skipping this step is the most common cause of a 502 error below.
Step 3: Create the site
- In IIS Manager, add a new website (or use Default Web Site), pointed at an empty folder, bound to your domain on port 80.
- Download the reverse-proxy config and save it as
web.config inside that folder: 📄 Download web.config.example
Step 4: Get an SSL certificate
- Download win-acme (a free Let's Encrypt client for Windows/IIS), extract it, and run
wacs.exe as Administrator.
- Choose the option to create a certificate for an IIS site, pick your Kindie site, and follow the prompts — it also binds the certificate and adds the HTTPS (443) binding to your site for you.
Use https://your-school.com (not http://SERVER_IP:1337) as the address you enter for BASE_URL in the setup wizard — every link in outgoing email is built from that value. This applies to both the Nginx and IIS paths above.
Backup & Restore
Backing up and restoring the MongoDB database.
🧰 Before you start: install the backup tools
The commands below need mongodump and mongorestore (MongoDB Database Tools). These are not included with the MongoDB server install and must be installed separately:
- Followed Windows Installation or Linux Installation already? You installed these as part of that page — nothing more to do.
- Docker Quick Start? The tools already exist inside the
mongodb container — nothing to install on your host. Use docker exec as shown below instead of running mongodump directly.
- Otherwise, download them from the MongoDB Download Center (Windows: run the
.msi; Linux: sudo apt-get install -y mongodb-database-tools; macOS: brew install mongodb-database-tools).
Check they're installed: mongodump --version
💾 Manual backup / restore
Windows Installation / Linux Installation / Other Platforms
| Action | Command |
|---|
| Back up the whole database | mongodump --host 127.0.0.1 --port 27017 --db kindiedb1 --out ./backup/kindiedb1 |
| Restore | mongorestore --drop --host 127.0.0.1 --port 27017 --db kindiedb1 ./backup/kindiedb1 |
Docker Quick Start
| Action | Command |
|---|
| Back up the whole database | docker exec kindie-mongo mongodump --db kindiedb1 --archive=/tmp/backup.gz --gzip && docker cp kindie-mongo:/tmp/backup.gz ./kindiedb1-backup.gz |
| Restore | docker cp ./kindiedb1-backup.gz kindie-mongo:/tmp/backup.gz && docker exec kindie-mongo mongorestore --drop --db kindiedb1 --archive=/tmp/backup.gz --gzip |
Replace kindiedb1 with the value of MONGO_DB_NAME in .env. Replace host, port, username, and password when MongoDB is on another server or requires authentication.
Restore replaces database records. Take a fresh backup before using --drop, stop the application during restore, and verify the database name and server first.
A complete backup also includes .env and, for disk storage, the assets/uploads and .tmp/chat-attachments directories when they exist. Store copies somewhere other than the same server.
🤖 Automatic daily backup (recommended)
Instead of typing the commands above by hand, download a ready-made script that backs up the database, .env, and uploads together in one run, and schedule it to happen automatically every day:
🔄 Updating Kindie to a new release
Always back up first (above) — an update should never be your first backup. The rest depends on how you installed.
Windows Installation / Linux Installation / Other Platforms
Step 1: Stop the application
- systemd:
sudo systemctl stop kindie
- Windows/NSSM:
Stop-Service Kindie
Step 2: Replace the application files
- Extract the new release into a new folder next to the old one (don't overwrite it in place — this is what makes rolling back possible). Copy your existing
.env and .install.lock into the new folder — a new release must not run the setup wizard again over an existing school. MongoDB and Redis are separate services, unaffected by which folder the app code lives in.
Step 3: Install and start
npm install, then point your service supervisor (systemd unit file / NSSM) at the new folder and start it — see "Running the Application".
Docker Quick Start
Do not extract the new release into a differently-named folder for Docker — Compose names its data volumes (mongo-data, redis-data) after the folder, so switching folders can make it look like your data disappeared (it's still there, just under the old folder's volume names).
Step 1
- In the same folder you already have, extract the new release on top of the old files —
.env and .install.lock are untouched since they're outside the image (bind-mounted).
Step 2
docker compose build
docker compose up -d
Check it worked
Open the site, sign in, and look at the logs (see "Running the Application") for startup errors before considering the update done.
⏪ Rolling back
Windows/Linux/Other Platforms: stop the new version, point your service supervisor back at the old folder (the one you kept, untouched), and start it again.
Docker: if you kept the old release files elsewhere (a zip or a copy made before Step 1 above), restore them into the same folder and run docker compose build && docker compose up -d again — the volumes are untouched either way, since they don't depend on the release files.
Either way: if the new version already changed data in a way the old version doesn't expect, restore the database backup taken before the update too — this is exactly why backing up first is not optional.
Other Platforms (macOS, other Linux)
Installing without Docker, for platforms not covered by the dedicated guides. On Windows without Docker, use "Windows Installation" instead; on Ubuntu without Docker, use "Linux Installation" instead — both already include this same "install Kindie" step. Use this page if you're on macOS, or a Linux distribution other than Ubuntu.
Windows and Ubuntu are the officially documented paths, with every command tested step by step. macOS and other Linux distributions work the same way in principle (Node.js + MongoDB + the same npm install / npm start), but the package-manager commands below are the standard ones for each platform rather than a path we test release by release — if a command doesn't match your exact distribution/version, adapt it or contact the Kindie team.
🛠️ Install the platform services first
Install these yourself using your platform's normal package manager, then come back here:
- Node.js 20.x — on macOS:
brew install node@20; on other Linux: use your distro's Node 20 package, or NodeSource.
- MongoDB 5.0+ — on macOS: MongoDB's Homebrew tap (
brew tap mongodb/brew && brew install mongodb-community@7.0); on other Linux: see MongoDB's official install docs for your distribution.
- MongoDB Database Tools (for backups —
mongodump/mongorestore) — on macOS: brew install mongodb-database-tools; on other Linux: see MongoDB's download page.
- Redis (optional — see "What's in the Box & Requirements") — on macOS:
brew install redis.
- Verify Node:
node -v (must be 20.x) and MongoDB: mongosh --eval "db.runCommand({ ping: 1 })".
📦 Install and start Kindie
Step 1: Install dependencies
npm install
Step 2: Start
npm start
No .env step — the first start opens the same setup wizard as the Docker path (see "First Run"), printing the setup link with its access token to your terminal.
The backend serves the pre-built admin interface itself (assets/react-backend-dist/) on the same port — no nginx or separate frontend server required. To put it behind nginx with HTTPS, proxy https://your-domain.com → 127.0.0.1:1337. Prefer nginx to serve the built files directly instead? Set SERVE_SPA=false.
Step 3 (optional): Rebuild the admin interface after customizing it
cd react-backend && npm install && npm run build -- single
# output goes to ../assets/react-backend-dist
The single build mode matters: it leaves the API URL empty so the admin talks to your own server, and forces the interface to English.
Automated / unattended deploys
- See "Application Configuration" → "Unattended / scripted deploys" for the
SKIP_INSTALLER option.
Mobile App Setup
The companion app for parents and teachers is Kindie App (Expo / React Native Web) — a separate item from the Web Admin. This guide covers the Web/PWA release: a build that runs in the browser and installs to the home screen without an app-store download. Install the Web Admin first, then build the app pointed at your own server.
Every customer builds their own copy — there is no pre-built download for this app. Unlike the Web Admin, the server address is baked into the app when it's built, not read afterward — so a build made for one school's domain will not work for another's. You always run at least Steps 1–2 below with your own domain; Step 2 optionally becomes "customize the source code, then build" if you want to change branding, add features, etc. before building.
⚙️ Requirements
- Your Web Admin backend already installed and reachable (see previous sections).
- Node.js 20.11.0 and Yarn 1.x — use
yarn, not npm install, to keep the lockfile correct. Running yarn install pulls in Expo's build tooling automatically — no separate global Expo/EAS CLI install needed.
🔧 Point the app at your server
Before building for production, edit src/config/config.prod.ts in the app source and replace the sample API/file URLs with your own domain — do not ship a build pointing at localhost or at someone else's domain:
EXPO_PUBLIC_API_URL=https://your-domain.com
EXPO_PUBLIC_FILE_URL=https://your-files-domain.com
Your Web Admin's CORS settings — and its WebSocket setup, if you use realtime chat — must allow the domain you deploy the PWA to.
📦 Build and deploy
Step 1: Install and build
yarn install
yarn build
This runs expo export -p web, generates the Workbox service worker, and writes the deployable files to dist/.
Step 2: Deploy
- Upload the whole
dist/ folder to any static hosting with HTTPS — Web Push requires HTTPS in production.
🔔 Push notifications
Web Push uses your own Firebase project — client config in src/firebase.ts and public/firebase-messaging-sw.js, VAPID public key in src/firebase.ts. Restrict your Firebase Web API key to your production domain in the Firebase/Google Cloud console. Never commit the Firebase Admin SDK service-account JSON to the app — that key belongs on the Web Admin server only.
Android and iOS native builds are not part of this Web/PWA release — contact the Kindie team if you need native app builds.
Upgrading from Kindie v4
V5 is a new generation (React SPA + hardened API). There is no automatic data migration — and for a kindergarten you rarely need one: at the start of a school year, classes, fees and menus are set up fresh anyway.
🔄 Your options
- Recommended path: install V5 fresh, then re-import students, parents and staff via the Excel templates (health columns included). Keep your v4 instance read-only for one school year for historical lookups.
- Staying on v4: fine — the
v4-legacy/ folder contains the previous version. v4 receives critical fixes only until 2026-12-31.
- Need help moving? A paid migration-assist service is available — contact the Kindie team.
Contact & Support
How to reach us, and where to find answers to common problems.
Hit a problem? Open the Troubleshooting tab at the top and choose Installation & Setup.
💬 Support
- Email: zinisoft.net@gmail.com · WhatsApp: +84 983 870 342
- Support hours: working days 8:00–17:00 (GMT+7), response within 1 working day
- Item support follows the standard Envato item support policy (6 months included, extendable at checkout). Free lifetime updates: enable update notifications at codecanyon.net/downloads
