Installation
SnapCart ships as a ready-to-run package with a browser-based installer wizard. No command-line configuration is needed — the wizard collects all settings and sets everything up automatically.
Prerequisites
The only software required on the server before you begin is Docker and Docker Compose. Everything else (Java, Node.js, MySQL, nginx) runs inside containers.
| Requirement | Minimum version |
|---|---|
| Docker | 20.x or later |
| Docker Compose | v2 (plugin) |
| RAM | 2 GB free |
| Disk | 2 GB free |
| Port 80 | Must be available (not in use by another service) |
To install Docker on Ubuntu:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
Verify both tools are ready:
docker --version
docker compose version
Step 1 — Upload the Package to Your Server
You will receive the SnapCart package as a .zip file. Upload it to your server using any SFTP client (FileZilla, WinSCP, Cyberduck) or the scp command:
scp snapcart.zip user@your-server-ip:/home/user/
Then SSH into the server and extract it:
ssh user@your-server-ip
unzip snapcart.zip -d snapcart
cd snapcart
Your folder should now look like this:
snapcart/
├── backend/
├── frontend/
├── installer/
├── nginx/
├── storage/
├── start.sh
├── docker-compose.yml
└── ...
Step 2 — Start the Containers
From inside the snapcart/ folder, run the bootstrap script:
bash start.sh
The script will:
- Check that Docker and Docker Compose are installed and running
- Create the
storage/directory if it does not exist - Start all containers in the background (
docker compose up -d) - Print the URL to open in your browser
When it finishes you will see output like:
✓ Docker found: Docker version 27.x.x
✓ Docker daemon is running
✓ Docker Compose found: 2.x.x
Starting SnapCart…
✓ SnapCart is starting up!
Open your browser and go to:
http://165.22.210.37
The installation wizard will guide you through the rest.
This takes about 2 minutes to complete.
Docker builds the application images on first run — this typically takes 3–5 minutes depending on your server speed. To watch the build progress:
docker compose logs -f
:::info Alternative — run Docker Compose directly
If you prefer not to use the script, you can start everything manually from inside the snapcart/ folder:
mkdir -p storage
docker compose up -d
:::
Wait until the installer container has started, then proceed to the next step.
Step 3 — Open the Installer
Open a browser and navigate to the URL printed by start.sh — or go directly to:
http://your-server-ip/install
Note: If you see a "Not Installed" page instead of the wizard, wait 30 seconds and refresh — the containers may still be starting up.
Step 4 — System Requirements Check
The first screen runs automatic checks on your server environment — Docker access, available disk space, memory, and whether port 80 is free.
Each check will show one of three states:
| Icon | Meaning |
|---|---|
| ✅ Pass | The check succeeded — no action needed |
| ⚠️ Warning | The check passed but something is not ideal — you can still proceed |
| ❌ Fail | A required condition is not met — you must fix this before continuing |
If any check shows Fail, follow the fix instructions shown on screen, then click Re-run Checks.
Once all required checks pass, click Next.
Step 5 — Database Configuration
Enter the credentials for your MySQL database.
| Field | Description |
|---|---|
| Host | Database server hostname or IP. Use db if using the built-in Docker database |
| Port | MySQL port — default is 3306 |
| Database Name | Name of the database to create/use (e.g. snapcart) |
| Username | MySQL user that SnapCart will connect as (e.g. snapcart) |
| Password | Password for the above user |
| Root Password | MySQL root password — used only during initial setup |
Click Test Connection to verify the credentials before proceeding.
:::tip Using the built-in database If you want to use the MySQL database included in the Docker Compose setup (recommended for most installs), enter:
- Host:
db - Port:
3306 - Database:
snapcart - Username:
snapcart - Password: any password you choose
- Root Password: any root password you choose
The database and user will be created automatically on first boot. :::
Once the connection test passes, click Next.
Step 6 — Application Settings
Enter the public-facing URL of your store and configure email delivery.
Public URL
| Field | Description |
|---|---|
| Store URL | The full public URL where your store will be accessible (e.g. http://165.22.210.37 or https://mystore.com) |
This URL is used for generating links in emails, CORS settings, and license domain validation. Enter the exact URL customers will use to access the store — including the protocol (http:// or https://).
Email (SMTP)
SnapCart sends emails for order confirmations, password resets, and notifications. Fill in your SMTP provider details:
| Field | Description |
|---|---|
| SMTP Host | Mail server hostname (e.g. smtp.gmail.com) |
| SMTP Port | Usually 587 (TLS) or 465 (SSL) |
| Username | Your SMTP login / email address |
| Password | Your SMTP password or app-specific password |
| From Email | The address emails will be sent from (e.g. noreply@mystore.com) |
Click Test SMTP to send a test email and verify the connection.
:::info SMTP is optional You can skip SMTP configuration during installation and set it up later from Admin → Settings → Email. Emails will simply not be sent until SMTP is configured. :::
Once done, click Next.
Step 7 — License Key
Enter your SnapCart license key. You can obtain your license key from license.btosc.com.
| Field | Description |
|---|---|
| License Key | Paste the full license key (JWT token) from license.btosc.com |
| Domain | The domain or IP this installation is for — must match the domain the license was issued for |
Click Verify License to validate the key.
:::info License is optional You can skip the license step and activate your license after installation from Admin → License. The application will display a warning banner until a valid license is activated. :::
Once verified (or skipped), click Next.
Step 8 — Super Admin Account
Create the first administrator account. This account will have full access to everything in the admin panel.
| Field | Description |
|---|---|
| First Name | Admin's first name |
| Last Name | Admin's last name |
| Email Address | Login email — used to sign in to the admin panel |
| Password | Choose a strong password (minimum 8 characters) |
Important: Store this password safely. If you lose it, you will need to reset it directly in the database.
Click Next to proceed to installation.
Step 9 — Installing
Click Install Now to begin. The installer will run through the following steps automatically, showing real-time progress:
| Step | What happens |
|---|---|
| Writing configuration | Generates the .env file with all your settings |
| Waiting for database | Waits for MySQL to finish loading the schema |
| Starting services | Starts the backend (Spring Boot) and frontend (React) containers |
| Waiting for application | Polls the backend health endpoint until it is ready |
| Creating super admin | Inserts your admin account into the database |
| Finalising | Writes the installation lock file — the installer is now disabled |
This process typically takes 2–4 minutes. Do not close the browser while it is running.
Step 10 — Installation Complete
When the progress bar reaches 100%, installation is complete. Click Go to Admin Panel to open your store's admin interface.
Accessing Your Store
After installation, your store is accessible at:
| URL | Purpose |
|---|---|
http://your-server-ip/admin | Admin panel — manage products, orders, users |
http://your-server-ip/ | Customer-facing storefront |
Sign in with the email and password you entered in Step 8.
Follow the First Login guide to complete your initial store configuration (store name, currency, payment methods, and more) before going live.
Troubleshooting
The installer page shows "Not Installed" instead of the wizard
The containers are still starting. Wait 30–60 seconds and refresh the page. Check container status with:
docker compose ps
start.sh reports "Docker is not installed"
Install Docker first, then re-run the script:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
bash start.sh
System check fails: "Docker socket not accessible"
The Docker socket must be mounted into the installer container. This is already configured in the provided docker-compose.yml — ensure you are running from the correct snapcart/ folder and have not modified the compose file.
Database test fails: "Access denied"
Double-check the username, password, and database name. If using the built-in db container, the container may still be initialising — wait a minute and try again.
Installation fails at "Starting services"
Docker may not have enough resources to build the backend image. Check available disk space and memory:
df -h
free -h
Cannot access the admin panel after installation
Confirm the containers are all running:
docker compose ps
All four services (db, backend, frontend, nginx) should show status Up. If any are stopped, check their logs:
docker compose logs backend
docker compose logs frontend
Installer page shows "410 Gone" after installation
This is expected — the installer is automatically disabled once installation is complete. Access your store at http://your-server-ip/admin.