---
title: "Deploy Opencart"
description: "Deploy OpenCart 4 store + MySQL on Railway. Persistent, free, one-click."
category: "Other"
url: https://railway.com/deploy/opencart
---

# Deploy Opencart

Deploy OpenCart 4 store + MySQL on Railway. Persistent, free, one-click.

**[Deploy Opencart on Railway](https://railway.com/template/opencart)**

- **Creator:** BURNI80
- **Category:** Other

## Template content

### opencart https://pb.dashboardicons.com/api/files/community_gallery/y47v24b46g477xh/opencart_2_6owwx2wnk5.png

- **Source:** https://github.com/BURNI80/opencart-railway-template
- **Health check:** /
- **Public domain:** Yes

## Documentation

# Deploy and Host opencart-railway-template on Railway

**What is opencart-railway-template?**

A ready-to-deploy template for **OpenCart 4.1.0.4** on Railway. One-click deploy spins up a full storefront and admin panel in a single container, with an embedded MariaDB and a persistent volume so your data survives every redeploy. Fully automatic installation — you only provide your admin credentials at deploy time. Free-tier friendly, zero manual configuration, built for small to medium e-commerce stores.

## About Hosting opencart-railway-template

Hosting this template deploys a **single OpenCart service** built from the public GitHub repo — Apache 2.4 + PHP 8.1 with an **embedded MariaDB** all inside one container, keeping cost to a minimum. On first boot an idempotent installer creates the schema, imports the demo data, and creates your admin user — all driven by environment variables, so no install wizard is needed. Database data lives on a **persistent volume mounted at `/var/lib/mysql`**, so products, orders and settings survive every redeploy. Railway handles HTTPS, the public domain, and the healthcheck for you.

## Common Use Cases

- Launching a production e-commerce storefront with admin panel in minutes.
- Standing up a demo / staging OpenCart shop to test extensions and themes.
- Building a lightweight, zero-maintenance online catalog or product listing site.

## Dependencies for opencart-railway-template Hosting

- **OpenCart application service** — built from the GitHub repo (`BURNI80/opencart-railway-template`).
- **Embedded MariaDB** — runs inside the same container, so no separate database service is required.
- **Persistent volume** mounted at `/var/lib/mysql` for database durability.

### Implementation Details 

The three admin fields **(username, email, and password)** are required at deploy time — they are *not* hardcoded, so each store gets unique, secure credentials. All other settings have sensible defaults and can be overridden with environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `ADMIN_USERNAME` | Admin panel username | *(required)* |
| `ADMIN_PASSWORD` | Admin password (min. 5 chars) | *(required)* |
| `ADMIN_EMAIL` | Admin email | *(required)* |
| `DB_PREFIX` | Database table prefix | `oc_` |
| `HTTP_SERVER` | Public store URL (from `RAILWAY_PUBLIC_DOMAIN`) | auto-detected |
| `MYSQLHOST` | External DB host (optional) | embedded |
| `MYSQLPORT` | Database port | `3306` |
| `MYSQLUSER` | Database user | `opencart` |
| `MYSQLPASSWORD` | Database password | `opencart` |
| `MYSQLDATABASE` | Database name | `opencart` |

---

## Deploying on Railway

1. Click the **Deploy on Railway** button (or open the template page).
2. In the form, enter your **admin credentials** (username, password, email).
3. Railway builds the image and mounts the persistent volume at `/var/lib/mysql`.
4. Wait 2–4 minutes for the first deploy to finish (the healthcheck verifies the store responds).
5. Open your URL to see the store, then go to `/admin/` with the credentials you set.

### Recommended post-deploy configuration
1. **Configure your store:** System → Settings (name, email, currency, etc.).
2. **Add products:** Catalog → Products.
3. **Enable payments & shipping:** Extensions → Extensions.
4. *(Optional)* Enable **SEO URLs:** System → Settings → Server → Enable SEO URLs (rewrite rules are already included in Apache).

---

## Included Components

| Component | Detail |
|-----------|--------|
| **Web server** | Apache 2.4 (`mod_rewrite` + `headers`), MPM prefork |
| **PHP** | 8.1 with `gd` (JPEG/FreeType), `mysqli`, `mbstring`, `zip`, `bcmath`, `pdo_mysql` |
| **Database** | **Embedded MariaDB** starting inside the same container (`127.0.0.1:3306`) |
| **OpenCart** | 4.1.0.4 — storefront + admin panel |
| **Persistent data** | Volume mounted at `/var/lib/mysql` (survives redeploys) |

At boot, an automatic installer checks whether the database is already installed:

- **First deploy:** creates the 159-table schema, imports the demo data, and creates the admin user.
- **Later deploys:** if the admin already exists it does **not** reinstall — it only regenerates the `config.php` files from environment variables and starts.

> **Want to use an external database instead of the embedded one?** The template uses **embedded MariaDB** by default (zero configuration). If you already have a MySQL/MariaDB service on Railway, just set `MYSQLHOST` (e.g. `mysql.railway.internal`) and the template will connect to **that** database instead of starting the embedded one.

---

## Persistence & the Security Notice

- All store data (products, orders, customers, config) lives in MariaDB → **volume `/var/lib/mysql`**. It survives every redeploy.
- OpenCart's storage (`system/storage/`) lives inside the container and is regenerated on each boot. To persist uploads/cache across deploys, mount volumes on the specific subfolders (not over the whole `system/storage`, which contains the Composer `vendor/`).

---

## Estimated Cost

- **Free tier / credit plan:** this deployment uses **1 service + 1 volume**, so it fits comfortably inside the monthly free credit of a Hobby/development plan. Ideal for small or test stores.
- Using a single container keeps both the volume and the active service at minimum consumption.

---

## Troubleshooting

### "Warning: the folder /var/www/ need to be writable"
A **security notice** from OpenCart, not an error. This template avoids it by making `/var/www` writable (`www-data` owner, `chmod 775`) at boot. Do **not** follow the advice to *move* the storage folder out of the document root — the Composer `vendor/` lives inside `system/storage/vendor`, and moving it breaks the storefront.

### "Error: Class Twig\Loader\FilesystemLoader not found"
Happens if `DIR_STORAGE` stops pointing at `system/storage/` (where `vendor/` lives). The template sets it correctly — do not force storage to another path.

### "Database Connection Failed"
- Only happens if you configured an external `MYSQLHOST` and the connection failed. Check host/port/user/password.
- With the embedded database (default) this should not occur.

### 500 Internal Server Error
- Check the deploy logs in the Railway dashboard for the specific PHP error.
- Verify environment variables don't contain broken values.

### SEO URLs / 404 links
- The Apache rewrite rules are already included (`apache-opencart.conf`).
- Enable "SEO URLs" in System → Settings → Server and clear the cache (dashboard refresh icon).

---

## Project Structure

```
├── Dockerfile              # PHP 8.1-Apache image with embedded MariaDB
├── docker-entrypoint.sh    # Starts DB, installs OpenCart, configures Apache
├── install.php             # Idempotent installer (schema + data + admin)
├── apache-opencart.conf    # VirtualHost with SEO rewrite rules
├── docker-compose.yml      # For local development
├── .env.example            # Reference environment variables
└── README.md               # Full documentation
```

---

## License

GPL v2 — the same as [OpenCart](https://github.com/opencart/opencart/blob/master/LICENSE.md).

---

## Why Deploy opencart-railway-template on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying opencart-railway-template on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/opencart