First Setup

After completing the installation, you need to configure the system with an administrator account, initial departments, tax rates, and products. This page guides you through the essential first-time setup steps.

Creating the Admin User

The first user must be created through the command line. Run the following command from the HQ server directory:

cd apps/hq-server
cargo run -- create-admin --name "Admin" --pin 1234

This creates a user with the SuperAdmin role, which has unrestricted access to every feature in the system. The PIN is what you will use to log into the HQ Manager web interface. Choose a secure PIN -- four to eight digits are supported. You can change it later from within the application.

Configuring the HQ Server

The HQ server reads its configuration from environment variables or a .env file in the apps/hq-server directory. The key settings to review are:

DATABASE_URL=postgres://pos:pos@localhost:5432/pos_hq
REDIS_URL=redis://localhost:6379
HQ_SERVER_PORT=3000
JWT_SECRET=change-this-to-a-random-string
SYNC_LISTEN_PORT=3001

The JWT_SECRET must be a strong, random string in production. The SYNC_LISTEN_PORT is the WebSocket port that stores will connect to for data synchronization. Make sure both ports are accessible from your store network.

Logging into HQ Manager

Start the HQ server and the HQ Manager frontend, then open your browser to http://localhost:5173/hq. Enter your admin PIN on the login screen. Once authenticated, you will see the HQ Manager dashboard with navigation to all management sections.

Setting Up Departments

Departments organize your products into logical categories (e.g., "Grocery", "Dairy", "Beverages"). Navigate to HQ Manager > Departments and create your top-level departments first. You can nest departments to create a hierarchy -- for example, "Beverages > Soft Drinks" and "Beverages > Juices". Each product must belong to exactly one department, so plan your structure before adding products.

Configuring Tax Rates

Navigate to HQ Manager > Tax Rates to define the tax rates applicable to your business. Tax rates are expressed in basis points: for example, a rate of 825 represents 8.25%. This avoids floating-point rounding issues in financial calculations. Create all the tax rates you need (e.g., "Standard Sales Tax" at 825, "Reduced Rate" at 400, "Tax Exempt" at 0). You will assign these rates to individual products.

Adding Your First Products

Go to HQ Manager > Products and click "Add Product". Each product requires a SKU (unique identifier), a barcode (for scanner lookup), a name, a selling price, a cost price, a department, and a tax rate. You can enter products one at a time through the form, or use the bulk import feature to upload a CSV file with your product catalog. Once saved, products are queued for synchronization to all connected stores.

After completing these steps, your HQ is configured and ready. The next step is to provision your first store.