DMS-O2

Die Management System

Local Area Network (LAN) platform for die tracking, inventory management, and audit histories.

DMS-O2 tracks precision drawing dies, machine allocations, and monthly inventory counts across manufacturing shop floors.

Overview & Architecture
Core Workspaces
Key Features
Technology Stack
Quick Start
- Prerequisites
- Installing mkcert
- Automated Setup
- Manual Setup (Alternative)
- Access Interfaces
Deploy with Docker (No Source Code)
Configuration
Project Structure
Usage Guide
- Using Make (Recommended)
- Common Container Tasks
- Keyboard Navigation
Deployment & Upgrades
Backup & Recovery
- Command Utility (dms-backup.sh)
Security
- TLS Certificates & Root CA
Client & User Access Installation Guide
- Step 1: Copy the Root CA
- Step 2: Install the Certificate on the Client
- Step 3: Verify the Connection
- Regenerating Certificates
Roadmap
FAQ
Troubleshooting
- Full Docker Reset (Nuclear Option)
Licensing & Compliance
Contributing
Support
Credits

Overview & Architecture

DMS-O2 uses a hybrid query execution design: fuzzy text searches route to Meilisearch, while numeric range queries run directly on PostgreSQL. The architecture delivers sub-millisecond read latency over LAN.

graph TD
    User([LAN Operator / Admin]):::client -->|HTTP/HTTPS| Traefik[Traefik v3 Reverse Proxy]:::proxy
    
    subgraph Container Stack [Container Stack]
        Traefik -->|/api/go/*| GoAPI[Go Search API Microservice]:::backend
        Traefik -->|/api/* & /admin/*| Django[Django 4.2 Web Server]:::backend
        Traefik -->|/*| Nginx[Nginx Static Frontend Server]:::proxy
        
        Django -->|Celery Workers| Celery[Celery Tasks]:::celery
        Django -->|Relational SQL / Audit Signals| Postgres[(PostgreSQL 18)]:::db
        
        GoAPI -->|Fuzzy Lookup| Meili[(Meilisearch v1.7)]:::db
        GoAPI -->|Cache Store| Redis[(Redis 7)]:::db
        GoAPI -->|Range Queries| Postgres
        
        Postgres -->|LISTEN/NOTIFY Cache Invalidation| GoAPI
    end

    classDef client fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0369a1;
    classDef proxy fill:#ecfdf5,stroke:#059669,stroke-width:2px,color:#047857;
    classDef backend fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px,color:#6d28d9;
    classDef db fill:#fffbeb,stroke:#d97706,stroke-width:2px,color:#b45309;
    classDef celery fill:#fdf2f8,stroke:#db2777,stroke-width:2px,color:#be185d;

See docs/ARCHITECTURE.md for architectural specifications.

Core Workspaces

Workspace	Primary Purpose	Key Capabilities
Die Tracking Dashboard	Real-time plant telemetry & status cards	KPI stats with glow borders, search bar with autocomplete, status donut breakdown, maintenance queue
Die Inventory	Master registry for round & flat dies	Filter by status/casing/machine, CAD vector blueprint sync, 2D/3D visual inspection
Machine Sets	Machine allocations & rack placement	Drag-and-drop storage rack map, set configuration, operational active/inactive ratio
Die Set Planner	Engineering capacity & procurement	Preset series calculators, bottleneck deficit analysis, recount sheets, Excel/CSV audit import
Engineering Suite	Wire drawing & sizing physics engine	Siebel's force formula, elongation analysis, 3D von Mises stress heatmap, PDF/Excel export
Audit History	Immutable field-level change ledger	Trigger-backed change history, timestamps, operator identity, exportable audit trail
Settings & Security	System administration & access control	System theme switcher, 2FA setup, wear tolerance alert limits, database backup/restore

Key Features

Triple System Themes: Real-time instant switching between Classic Slate (vibrant industrial midnight UI with glowing KPI status cards), Dark Terminal (high-density Bloomberg monospace), and Precision Light (clean high-contrast daylight mode).
Precision Die Modeling: Custom tracking templates for round dies (casing, current size, original size) and flat dies (width, thickness, corner radius). Supports statuses: AVAILABLE, RUNNING, CLEANING, POLISHING, DAMAGED, SCRAPPED, MISSING, MAINTENANCE.
Modular Die Set Planner & Capacity Engine: Multi-source stock ingestion (DMS database, live enamel machines, monthly audit recount sheets), bottleneck deficit analytics, series capacity planning, and target set procurement forecasting with 5-decimal precision.
Enamel Machine Tracking & Monthly Recount Audit Sheets: Machine die allocation ledger and spreadsheet-grade monthly physical inventory audit sheets with Excel/CSV drag-and-drop import and discrepancy reports.
Single-Use Backup Codes Authentication: Cryptographically hashed (SHA-256) one-time recovery codes for secondary sign-in security without requiring mobile authenticator apps.
Real-Time Live SSE Event Distribution: Redis Pub/Sub multiplexing PostgreSQL LISTEN/NOTIFY events across multi-container instances with automatic local fallback.
Interactive CAD Highlighting: Bidirectional vector sync between table dimensions and blueprint SVG nodes.
Visual Storage Rack Map: Drag-and-drop grid interface for physical warehouse rack management.
Fuzzy & Parametric Search: Sub-millisecond lookups via Go microservice with Redis caching, PostgreSQL range queries, and Meilisearch.
Granular Role-Based Access Control (RBAC):
- Unauthenticated / Operator: Read-only search, metrics, and inventory browsing.
- Admin: Full CRUD on dies, machines, and sets, plus bulk spreadsheet imports.
- Root: User administration, database backup/restore, and system configuration.
Immutable Auditing: Database triggers and Django signals capture all modifications to die status, location, and dimensions.
Session Management: Single active session enforcement with immediate revocation on new sign-in.
Sheet-to-Database Import: Validation-backed, idempotent CSV/Excel import system.
3D Stress Analysis: WebGL von Mises stress heatmaps with angle/bearing sliders, cutaway planes, crack defect overlays, and snapshot export.
Engineering Workbench: CAD geometry inspector, deformation simulator, Siebel's force calculations, and trade-off comparison matrices.
Granular Tool Permissions: Per-user feature toggles with real-time background auth sync.
Frontend Resilience: Automatic chunk load error recovery and update fallback handling.
Engineering Calculators: Sizing & elongation calculator, wire drawing calculator with interactive results, and PDF/Excel/CSV exports.

Technology Stack

Layer	Component	Version	Role / Purpose
Frontend UI	React, Vite, Vanilla CSS	`React 18`, `Vite`	Single Page Application (SPA) dashboard
Backend API	Django & Django REST Framework	`Python 3.11`, `Django 4.2`	Core business logic, RBAC policies, mutating transactions
Search Gateway	Go (Golang)	`Go 1.22`	Ultra-fast read-only query processing & cache management
Relational DB	PostgreSQL	`PostgreSQL 18`	Primary relational store & immutable auditing
Fuzzy Index	Meilisearch	`v1.7`	Typo-tolerant text index for rapid search
Memory Cache	Redis	`v7` (Alpine)	Query caching & Celery broker
Ingress Router	Traefik	`v3`	Automated HTTPS TLS termination & reverse proxy
Testing	Vitest, Playwright, PyTest	—	Front-to-back unit, integration, and E2E coverage

Quick Start

Prerequisites

Ensure you have the following installed on your host machine:

Docker & Docker Compose (V2+): On Linux, configure your user to access the Docker daemon without sudo:
```
sudo usermod -aG docker $USER
# Log out and log back in for changes to take effect
```
mkcert / OpenSSL: Required for local TLS certificate generation. If mkcert is missing or blocked by Windows Application Control policies (AppLocker/WDAC), the setup script automatically falls back to Git OpenSSL.
Node.js (v18+) & npm: Only required if running the frontend locally outside Docker.
Python 3.11: Only required if running Django commands locally outside Docker.

Installing `mkcert`

Choose the command matching your host operating system:

Operating System	Install Command
Linux (Fedora/RHEL)	`sudo dnf install mkcert`
Linux (Debian/Ubuntu)	`sudo apt install mkcert`
macOS (Homebrew)	`brew install mkcert`
Windows (Chocolatey)	`choco install mkcert`

Alternatively, download binaries directly from the official releases.

Automated Setup

The setup scripts automate container builds, database initialization, and certificate generation.

Linux & macOS

chmod +x setup.sh
./setup.sh

Windows (1-Click / Terminal)

You can double-click setup.bat or run:

setup.bat

Or run directly in PowerShell (execution policy is automatically bypassed for the session):

.\setup.ps1

Tip

Using Make A Makefile is provided for developer convenience. Run make help to see all available targets (setup, certs, start, stop, logs, backup, etc.).

Tip

LAN Network Access On completion, the setup scripts output your server's LAN IP address (e.g., https://192.168.1.15). Any device on the same local network can access the dashboard. To remove SSL browser warnings on client machines, see Client & User Access Installation Guide.

Manual Setup (Alternative)

If you prefer to configure the steps manually:

Environment Settings:
```
cp .env.example .env
```

Generate TLS Certificates:

# Windows
scripts\generate-certs.bat

# Linux/macOS
chmod +x scripts/generate-certs.sh
./scripts/generate-certs.sh

Or generate directly with mkcert (replace YOUR_LAN_IP):

mkcert -install
mkcert -cert-file certs/cert.pem -key-file certs/key.pem localhost 127.0.0.1 YOUR_LAN_IP ::1

Start Services:
```
docker compose up -d --build
```

Run Database Migrations & Seeds:

docker compose exec django python manage.py migrate
docker compose exec django python manage.py create_root_user

Sync Search Indexes:

docker compose exec django python manage.py sync_search

Access Interfaces

Frontend SPA: https://localhost
Django Admin Console: https://localhost/admin/
REST API Root: https://localhost/api/
Default Credentials: Automatically generated by setup.sh (saved in your .env file).

Note

DMS-O2 forces HTTPS by default. The setup scripts automatically generate TLS certificates for your LAN IP using mkcert or OpenSSL. All plain HTTP requests are automatically redirected to HTTPS.

Deploy with Docker (No Source Code)

Deploy DMS-O2 using pre-built images without cloning the repository:

mkdir dms && cd dms
curl -LO https://raw.githubusercontent.com/sauryah/dms-o2/main/docker-compose.ghcr.yml
curl -LO https://raw.githubusercontent.com/sauryah/dms-o2/main/.env.example
cp .env.example .env   # ← Edit passwords and secret keys here!
docker compose -f docker-compose.ghcr.yml up -d

For detailed production deployment instructions, including Windows PowerShell/Command Prompt scripts, automated backups, and version pinning, review the Docker Deployment Guide.

Configuration

System variables managed in the .env file at the project root.

Warning

Ensure all secret keys and passwords are changed in production environments. Never commit .env files to git repositories.

Key	Default Value	Description
`POSTGRES_DB`	`dms`	Target PostgreSQL database name.
`POSTGRES_USER`	`dms_user`	Database user account.
`POSTGRES_PASSWORD`	`your_db_password`	Database access password.
`POSTGRES_HOST`	`db`	Database service host inside the Docker network.
`POSTGRES_PORT`	`5432`	PostgreSQL network port.
`REDIS_PASSWORD`	`change_me_redis_password`	Redis auth password (must match broker/backend URL).
`DJANGO_SECRET_KEY`	`your-secret-key`	Django secret key for session signing and CSRF protection.
`INTERNAL_API_SECRET`	`your-internal-secret`	Shared secret for Django ↔ Go API communication.
`CELERY_BROKER_URL`	`redis://:change_me_redis_password@redis:6379/0`	Redis connection URL for Celery message broker.
`CELERY_RESULT_BACKEND`	`redis://:change_me_redis_password@redis:6379/0`	Redis connection URL for Celery task results.
`MEILI_HOST`	`http://meilisearch:7700`	Search service connection endpoint.
`MEILI_MASTER_KEY`	auto-generated	Meilisearch authorization key.
`ROOT_USERNAME`	`root`	Superuser username.
`ROOT_PASSWORD`	(generated by setup.sh)	Default administrator password.
`SESSION_IDLE_TIMEOUT_MINUTES`	`30`	Minutes before idle session expires.
`SESSION_ABSOLUTE_TIMEOUT_HOURS`	`12`	Absolute hours before user is forced to log in again.

Project Structure

dms-o2/
├── .github/workflows/         # CI/CD Deployment configurations
├── .githooks/                 # Git hooks (pre-commit linting & secret detection)
├── backend/                   # Django Backend Service
│   ├── dms/                   # Core settings, URLs, Celery config
│   ├── dies/                  # Die models, signals, viewsets, services (recut, wear, import, search, validation)
│   ├── history/               # Audit logging (DieHistory, MachineHistory) and views
│   ├── machines/              # Assets (Categories, Machines, Sets, Racks)
│   ├── search/                # Celery Meilisearch indexing tasks and outbox processor
│   └── users/                 # RBAC, auth views, permissions, session management
├── certs/                     # TLS certificates (generated, gitignored)
│   ├── cert.pem               # Server certificate for current LAN IP
│   ├── key.pem                # Private key
│   └── rootCA.pem             # Root CA (install on client machines)
├── go-api/                    # Go Search & Stats Microservice
│   ├── cmd/server/main.go     # API routes and Redis invalidation cache logic
│   └── Dockerfile             # Multi-stage container file
├── frontend/                  # React Frontend Single Page Application
│   ├── src/                   # UI components, layout grids, hooks, contexts
│   ├── features/              # Feature-specific components (inventory, dashboard, wire-drawing-calculator)
│   └── Dockerfile.prod        # Production static Nginx configuration
├── scripts/                   # Utility scripts
│   ├── generate-certs.sh      # Auto-generate TLS certs (Linux/macOS)
│   ├── generate-certs.bat     # Auto-generate TLS certs (Windows)
│   ├── uninstall-certs.sh     # Uninstall Root CA and delete certs (Linux/macOS)
│   ├── uninstall-certs.bat    # Uninstall Root CA and delete certs (Windows)
│   ├── client-install-template.bat # Windows installer script template
│   ├── client-install-template.sh # macOS/Linux installer script template
│   ├── client-instructions-template.txt # Client cert installation instructions template
│   ├── install-cert.bat       # Install rootCA on Windows clients
│   ├── backup_db.sh           # Database backup script
│   └── prune_history.sh       # Audit history retention cleanup
├── docs/                      # Documentation folder
│   └── ARCHITECTURE.md        # Deep architectural design specs
├── design-system/             # CSS tokens and design specs
│   └── die-management-system/
│       └── MASTER.md          # Global design components and tokens
├── Makefile                   # Common dev commands (make help)
├── traefik.yml                # Traefik static config (entrypoints, providers)
├── dynamic.yml                # Traefik dynamic config (TLS store, certificates)
├── docker-compose.yml         # Local development compose stack
├── docker-compose.prod.yml    # Production compose stack
├── docker-compose.ghcr.yml    # Pre-built image compose stack
├── setup.sh                   # Automated setup (Linux/macOS)
├── setup.ps1                  # Automated setup (Windows)
├── deploy.sh                  # Production upgrade script
└── dms-backup.sh              # Database backup and restore script

Architecture Specs: Detailed layout rules can be found in docs/ARCHITECTURE.md.
Design Guidelines: Visual UI styling guidelines are located in design-system/die-management-system/MASTER.md.

Usage Guide

Using Make (Recommended)

Run make help to view available CLI tasks:

Command	Description
`make setup`	Full automated setup (Docker + DB + certs)
`make certs`	Regenerate TLS certificates for current LAN IP
`make uninstall-certs`	Remove all certificates and uninstall Root CA from system trust store
`make start`	Start all containers
`make stop`	Stop all containers
`make logs`	Tail all container logs
`make migrate`	Run database migrations
`make backup`	Run manual database backup
`make build`	Rebuild and restart all containers

Common Container Tasks

Start the stack:
```
docker compose up -d
```
Stop without deleting data:
```
docker compose stop
```
Bring down (removes containers and networks):
```
docker compose down
```
View logs:
```
docker compose logs -f
```

Database CLI:

docker compose exec db psql -U dms_user -d dms

Emergency Password Reset:

docker compose exec django python manage.py changepassword root

Emergency Backup Codes / 2FA Reset:

docker compose exec django python manage.py reset_mfa root

Keyboard Navigation

Optimized for shop-floor speed with keyboard shortcuts:

▲ ArrowUp / ▼ ArrowDown — Navigate up and down through list results.
Tab / Shift + Tab — Shift focus between input fields.
Enter — Select and view the highlighted inventory record.

Deployment & Upgrades

Production deployment uses high-concurrency configuration:

Nginx: Serves compiled React assets with Gzip compression.
Gunicorn: WSGI server for Django backend.
Go Endpoint: Bypasses Django for high-speed reads on /api/go/*.

Production Deployment Script

Deploy upgrades without downtime using the integrated deployment script:

./deploy.sh

This script pulls updates, verifies configuration, builds changed containers, runs migrations, and clears legacy caches.

Backup & Recovery

Automated nightly compressed database dumps at 2:00 AM with 14-day retention. Backups persist to ./backups/.

Command Utility (`dms-backup.sh`)

Create a manual backup:
```
./dms-backup.sh backup
```
List all local backups:
```
./dms-backup.sh list
```

Restore the database:

./dms-backup.sh restore <backup_filename.dump>

Warning

Restoring a database will overwrite current records and trigger an automatic rebuild of Meilisearch search indexes.

Security

DMS-O2 is built with security-first practices to protect industrial assets and maintain server integrity on local shop floor networks.

Core Security Controls

Container Isolation: All processes run under a non-root user (USER dmsuser).
CSRF Protection: Mutating cookie-based API calls require X-Requested-With: XMLHttpRequest.
HMAC Signing: Celery outbox task payloads validated via HMAC-SHA256.
Credential Validation: Startup checks prevent production mode with default credentials.
HTTPS Enforcement: Traefik auto-enforces TLS and redirects all HTTP traffic.
Session Integrity: Single active session policy with immediate revocation.
Timing-Safe Comparisons: Microservice secrets validated using hmac.compare_digest.
Redis Authentication: --requirepass enforced across all service connections.
Security Headers: Nginx serves X-Frame-Options, X-Content-Type-Options, Content-Security-Policy, and Permissions-Policy.
Input Validation: Parameterized SQL queries and strict shell script validation.
Task Safety: Backup restore tasks pass token hashes instead of raw JWTs.

TLS Certificates & Root CA

DMS-O2 secures network connections via HTTPS/TLS. Client devices must trust the server's Root CA to access the dashboard without certificate warnings.

Server Certificates: Auto-generated for your LAN IP during setup using mkcert. Stored in certs/ (gitignored), valid for 2 years. Regenerate with scripts/generate-certs.sh or scripts/generate-certs.bat.

For security issues, see Security Policy for responsible vulnerability reporting guidelines.

Client & User Access Installation Guide

To access DMS from another computer on the same LAN without certificate warnings, install the server's root CA certificate (rootCA.cer) on each client device.

Setup Workflow

graph LR
    Server[DMS Server certs/] -->|1. Copy rootCA.cer| Client[Client Computer]
    Client -->|2. Install Certificate| TrustStore[OS Trusted Root Store]
    TrustStore -->|3. Browse HTTPS| SecureConn[Secure HTTPS Connection]
    
    style Server fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0369a1;
    style Client fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px,color:#6d28d9;
    style TrustStore fill:#ecfdf5,stroke:#059669,stroke-width:2px,color:#047857;
    style SecureConn fill:#fffbeb,stroke:#d97706,stroke-width:2px,color:#b45309;

Step 1: Copy the Root CA

Copy certs/rootCA.cer (DER format, optimized for Windows) from the DMS server to the client machine via USB, network share, or email.

Step 2: Install the Certificate on the Client

Choose the method matching the client machine's environment:

Option A: Windows (Automated Script - Recommended)

Copy both certs/rootCA.cer and the installer script scripts/install-cert.bat to the same folder on the client machine.
Right-click install-cert.bat and select Run as Administrator.

Option B: Windows (PowerShell Command)

Install for Current User (No Administrator rights required):

certutil -user -addstore -f "Root" rootCA.cer

Or install System-wide (Run PowerShell as Administrator):

certutil -addstore -f "Root" rootCA.cer

Option C: Windows (Graphical User Interface)

Double-click rootCA.cer.
Click Install Certificate...
Select Local Machine and click Next.
Choose Place all certificates in the following store and click Browse.
Select Trusted Root Certification Authorities and click OK.
Click Next and click Finish.

Option D: Mozilla Firefox (All Platforms)

Firefox maintains an isolated certificate store:

Open Firefox and navigate to about:preferences#privacy.
Scroll to the Certificates section and click View Certificates...
Select the Authorities tab and click Import...
Select rootCA.cer and check Trust this CA to identify websites.
Click OK and restart Firefox.

Option E: Google Chrome / Microsoft Edge (Alternative)

If Chrome does not inherit the Windows system store automatically:

Go to chrome://settings/certificates.
Navigate to Authorities and click Import.
Select and import the rootCA.cer certificate.

Step 3: Verify the Connection

Navigate to https://<DMS_SERVER_IP> in the client browser. The connection should display a secure padlock with no warnings.

Regenerating Certificates

If the server's IP address changes, regenerate certificates:

# Linux/macOS
./scripts/generate-certs.sh

# Windows
scripts\generate-certs.bat

Or run mkcert directly (replace YOUR_LAN_IP):

mkcert -install
mkcert -cert-file certs/cert.pem -key-file certs/key.pem localhost 127.0.0.1 YOUR_LAN_IP ::1

After regeneration, restart Traefik and redistribute the new rootCA.cer:

docker compose up -d --force-recreate traefik

Roadmap

The current priorities and roadmap items for DMS-O2 include:

CAD Engine Extensions: DWG/DXF dimensional schematic import.
Expanded Analytics: Historical wear trends and predictive cycle life tracking.
Multi-Warehouse Syncing: Inter-facility inventory transfers with audit chain validation.
ScyllaDB Migration: High-throughput timeseries storage for die history logs.

FAQ

How is concurrent session eviction handled?

DMS enforces a single active session policy. Signing in from a new device immediately revokes the previous session (returning 401 Unauthorized).

How do I re-sync search indexes manually?

docker compose exec django python manage.py sync_search

Can unauthenticated users move dies?

No. Moving dies, adding records, or editing states requires Admin or Root permissions. Unauthenticated users are limited to search and view actions.

Troubleshooting

Below are solutions to common setup, network, and database issues. Click on a category to expand the troubleshooting steps.

Docker, Container & Port Issues

Symptom	Primary Cause	Resolution
Port conflict on 80/443	Another server (e.g., Apache or host Nginx) is active	Stop the host service: `sudo systemctl stop nginx` (or `apache2`), or change port bindings in `docker-compose.yml`. Both 80 and 443 must be available on the host.
Write/Compile permission denied	Root-owned files left in mounting volume	Clean the build artifact directory: run `docker compose exec frontend rm -rf dist` and restart.
Docker "permission denied" on Linux	User is not part of the `docker` group	Add your user: `sudo usermod -aG docker $USER`, then log out and log back in to refresh permissions.
`.env` secrets still show `auto:run_setup_to_generate`	The `.env` file already existed before running the setup script	Remove the incomplete env: `rm .env` (or `del .env` on Windows) and run `./setup.sh` (or `.\setup.ps1`) again.

SSL, HTTPS & LAN Network Issues

Symptom	Primary Cause	Resolution
Cannot connect/access from phone or external device	Server IP changed, host is not allowed in Django, or Windows network category is set to Public	DMS auto-detects the server IP during setup. If it fails, add the IP manually to `DJANGO_ALLOWED_HOSTS` in `.env` (e.g. `DJANGO_ALLOWED_HOSTS=...,192.168.1.15`) and restart: `docker compose restart django`. On Windows, run PowerShell as Administrator and execute `Set-NetConnectionProfile -InterfaceAlias Wi-Fi -NetworkCategory Private` to allow local routing.
Browser shows "Not Secure" or certificate warning	Root CA certificate not installed on client machine	Follow the Client & User Access Installation Guide to install `rootCA.cer`. For Firefox, import the certificate manually via `about:preferences#privacy`.
`ERR_CERT_AUTHORITY_INVALID` in Chrome	Chrome is ignoring the OS certificate store	Import the root CA directly via `chrome://settings/certificates` -> Authorities -> Import.
Certificate does not match IP (DNS/IP SAN error)	Server IP address changed after cert generation	Regenerate certificates using `./scripts/generate-certs.sh` (Linux/macOS) or `scripts\generate-certs.bat` (Windows), then reinstall the new root CA on client machines.

Database, Cache & Search Index Issues

Symptom	Primary Cause	Resolution
Meilisearch connection error	Mismatched host mapping	Inside Docker, ensure `MEILI_HOST=http://meilisearch:7700`. For direct local runs, set `MEILI_HOST=http://localhost:7700`.
Migrate fails with `MeilisearchCommunicationError`	Migration ran before Meilisearch fully initialized	Ensure `meilisearch` has a healthcheck in `docker-compose.yml` and the migrate service has `condition: service_healthy` in its `depends_on`. Run `docker compose up -d --build` to retry.
`password authentication failed for user "dms_user"`	DB volume retains old password, but `.env` has a new one	Clean out old volumes: `docker compose down -v`, then recreate stack: `docker compose up -d --build`. Note: This wipes database data; re-run migrations and seeds afterwards.
Dies missing from sidebar tree / showing 0 count	Database pagination limit exceeded	Increase the `pageSize` state variable in `frontend/src/features/inventory/hooks/useInventoryState.ts` and rebuild: `docker compose up -d --build frontend`.

Authentication, Sessions & Administration

Symptom	Primary Cause	Resolution
401 Unauthorized loops after login	Go API cannot check tokens because `DJANGO_ALLOWED_HOSTS` is missing the `django` service name	Add `django` to `DJANGO_ALLOWED_HOSTS` in `.env` (e.g. `DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,django`) and restart: `docker compose restart`.
401 Unauthorized loops (other)	Database was reset or session became invalid	Clear local storage / cookies in your browser's developer tools and log back in.
Locked out / forgot root password	Administrator credentials lost	Reset the password inside the container: `docker compose exec django python manage.py changepassword root`.
Locked out / lost backup recovery codes	User lost all single-use backup codes for secondary sign-in	Clear backup codes and disable 2FA challenge via server CLI: `docker compose exec django python manage.py reset_mfa root` (or specify any user: `... reset_mfa <username>`).

Full Docker Reset (Nuclear Option)

For corrupted Docker environments or complete resets, wipe all containers, images, networks, volumes, and build cache.

Warning

This command will delete ALL Docker data on your system, not just DMS-O2 resources. Ensure you have backed up any unrelated Docker work.

Linux / macOS:

sudo bash -c 'systemctl start docker && docker ps -aq | xargs -r docker rm -f && docker images -aq | xargs -r docker rmi -f && docker volume ls -q | xargs -r docker volume rm -f && docker network ls --filter type=custom -q | xargs -r docker network rm && docker builder prune -af && docker system prune -af --volumes'

Windows (PowerShell as Administrator):

docker rm -f $(docker ps -aq) 2>$null; docker rmi -f $(docker images -aq) 2>$null; docker volume rm -f $(docker volume ls -q) 2>$null; docker network rm $(docker network ls --filter type=custom -q) 2>$null; docker builder prune -af; docker system prune -af --volumes

Licensing & Compliance

DMS-O2 is a dual-licensed project designed to offer flexibility for both open-source development and proprietary commercial use:

Open Source (GNU AGPL-3.0): Free to run, copy, modify, and distribute. Network-hosted modifications must be disclosed under AGPL-3.0. See LICENSE.
Commercial License: For organizations requiring proprietary modifications without disclosure. See LICENSE-COMMERCIAL.md.

Additional details:

Copyright: COPYRIGHT.md
Trademarks: TRADEMARK.md

Contributing

Contributions welcome. See CONTRIBUTING.md for setup, testing, and CLA details.

Pre-commit Hooks

Included in .githooks/pre-commit to verify Python syntax, check for console.log statements, validate Dockerfiles, and detect secret leaks. Enable with:

git config core.hooksPath .githooks

Support

For deployment support, bug reports, and customization assistance, see Support Guide.

Credits

Developed for industrial manufacturing shop floors by Sahil Pradhan.

Name		Name	Last commit message	Last commit date
.dev		.dev
.githooks		.githooks
.github		.github
.vscode		.vscode
backend		backend
certs		certs
design-system/die-management-system		design-system/die-management-system
docs		docs
frontend		frontend
go-api		go-api
scripts		scripts
wiki		wiki
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYRIGHT.md		COPYRIGHT.md
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
LICENSE		LICENSE
LICENSE-COMMERCIAL.md		LICENSE-COMMERCIAL.md
Makefile		Makefile
PROJECT.md		PROJECT.md
README.md		README.md
REFACTOR_REPORT.md		REFACTOR_REPORT.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
TRADEMARK.md		TRADEMARK.md
deploy.sh		deploy.sh
dms-backup.sh		dms-backup.sh
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.ghcr.yml		docker-compose.ghcr.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.unified.yml		docker-compose.unified.yml
docker-compose.yml		docker-compose.yml
dynamic.yml		dynamic.yml
entrypoint.sh		entrypoint.sh
host-nginx.conf		host-nginx.conf
nginx-monolith.conf		nginx-monolith.conf
setup.bat		setup.bat
setup.ps1		setup.ps1
setup.sh		setup.sh
supervisord.conf		supervisord.conf
traefik.yml		traefik.yml

Latest commit

History

Folders and files

Repository files navigation

DMS-O2

Table of Contents

Overview & Architecture

Core Workspaces

Key Features

Technology Stack

Quick Start

Prerequisites

Installing mkcert

Automated Setup

Linux & macOS

Windows (1-Click / Terminal)

Manual Setup (Alternative)

Access Interfaces

Deploy with Docker (No Source Code)

Configuration

Project Structure

Usage Guide

Using Make (Recommended)

Common Container Tasks

Keyboard Navigation

Deployment & Upgrades

Production Deployment Script

Backup & Recovery

Command Utility (dms-backup.sh)

Security

Core Security Controls

TLS Certificates & Root CA

Client & User Access Installation Guide

Setup Workflow

Step 1: Copy the Root CA

Step 2: Install the Certificate on the Client

Option A: Windows (Automated Script - Recommended)

Option B: Windows (PowerShell Command)

Option C: Windows (Graphical User Interface)

Option D: Mozilla Firefox (All Platforms)

Option E: Google Chrome / Microsoft Edge (Alternative)

Step 3: Verify the Connection

Regenerating Certificates

Roadmap

FAQ

How is concurrent session eviction handled?

How do I re-sync search indexes manually?

Can unauthenticated users move dies?

Troubleshooting

Full Docker Reset (Nuclear Option)

Licensing & Compliance

Contributing

Pre-commit Hooks

Support

Credits

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Installing `mkcert`

Command Utility (`dms-backup.sh`)