Docs / Installation

Installation

Get Spicy running on the server. This should take about 20 minutes.

Spicy runs as a server. You can run it on the computer at your counter, or on a cloud server. Run the steps below on that server. When the server is in the cloud, each till needs an internet connection.

What you need

Requirement	Notes
A computer	This becomes your till. It stays on during trading.
Three thermal printers	Use one printer for receipts, one for the kitchen, and one for the bar. The kitchen and bar printers are on the network.
PostgreSQL	PostgreSQL holds all your data. Docker is the easiest way to run it.
Python 3.14+	Python runs Spicy.
Node.js and npm	Node.js builds the buttons and styling.
Docker	Docker runs PostgreSQL and Redis for you. It is optional, but we recommend it.

Use a wired connection for the till. Where possible, connect the cashier's computer with an Ethernet cable. If the network drops mid-shift, the system stops accepting orders. A cable is safer than Wi-Fi for this reason.

Install

Step 1: Get the code

git clone https://github.com/sanusi-dev/spicy.git
cd spicy

Step 2: Start the database

This command does four things:

make init

It copies a sample settings file.
It starts PostgreSQL and Redis.
It creates your database tables.
It installs the front end files.

It may take a few minutes on the first run while everything downloads.

Step 3: Start Spicy

make dev

Leave this running. Spicy is available at localhost:8000.

Step 4: Create your administrator account

While Spicy is running, open a second terminal in the same folder and run:

make manage ARGS='createsuperuser'

Pick a username and password. This is the administrator account. Use it to sign in and create accounts for your staff.

Step 5: Load the standard accounts

Spicy needs a set of accounts before it can record a sale — things like Food Sales, Cash Account, and Cost of Goods Sold. This command sets those up, along with sample items and prices so you can try things out.

make manage ARGS='seed_pos_setup'

Delete the sample items before you trade. They are placeholders. Delete them and add your own in Setup.

Check the installation

To check for problems, run:

make manage ARGS='check'

A healthy install reports System check identified no issues.

Before you take real orders

Do three things first.

Disable debug mode

Open the .env file and set:

DEBUG=False

Debug mode is for development. If you leave debug mode on, anyone signed in as an administrator can change your sales and stock figures directly. These changes bypass the safety checks. Do not trade with debug mode on.

Set your own secret key

Run this to generate one:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Paste the result into the SECRET_KEY line in .env. This key protects your staff logins. If you skip it, anyone who reads the public source can sign in as your staff.

Set your time zone

Spicy uses the server's clock to decide which trading day a sale belongs to. If you close at 3am, that sale still counts for the previous day. Make sure the server's date, time, and time zone are accurate. Check the automatic time setting on the server.

Printing

Spicy prints through a small helper on the same computer. The helper connects to your receipt printer directly and to the kitchen and bar printers over the network.

Once the helper is running, add each printer in Setup under Production Units. For each printer, enter its IP address, its paper width, and whether it prints receipts or tickets. Also set whether it cuts the paper off after printing.

A printer problem will not stop you selling. If Spicy cannot reach a printer, the sale still completes and you get a warning. But the kitchen will not receive the food, so the kitchen will not cook the food. Fix the printer before you trade.

Running it every day

Every morning, do these steps:

Start Docker and the database: make start-bg
Start Spicy: make dev
Open the POS and open your shift

You can leave make dev running in a terminal window. But if you close that window, or sign out of the server, Spicy stops. For a permanent installation, ask the person who installed Spicy to run Spicy as a service that starts automatically.

Backing up

From day one, take a backup every night:

make backup

This saves your sales data and your item photos to the backups folder. Set it to run automatically after closing time. Copy the files to another drive each week. A backup sitting on the same computer does not help if that computer is stolen.

Run it once manually now, before you have any real data. Then you know that it works, and you know where the files are.

Spicy is running, but it does not have your restaurant data yet. Continue with Setup.