Quick Start
Deploy MySagra on your server in four steps β no prior configuration needed.
Prerequisites
Make sure the following tools are installed on the machine that will run MySagra.
Docker (with Compose v2)
MySagra runs entirely inside Docker containers. Install Docker Desktop (Windows / macOS) or Docker Engine + Docker Compose (Linux) from the official site:
docs.docker.com/get-docker βConfigure your stack
Select the services you need. Copy each generated file (docker-compose.yml, .env, and nginx.conf if using Nginx) into a new folder on your server.
Choosing the right SERVER_IP
- Private / local deployment β use your server's LAN IP address (e.g.
192.168.1.100). The self-signed certificate generated by mkcert in Step 2 will be valid exactly for that address. - Public / internet-exposed deployment β point a real domain name to your server and use a certificate issued by a trusted CA such as Cloudflare, Let's Encrypt, or similar. This way browsers will trust the certificate automatically β no need to install a root CA on every device.
Before copying the generated files, open the .env tab and set SERVER_IP to your server's actual IP address or hostname. This value is used both by the services at runtime and by mkcert in Step 2 to generate a certificate valid for that address.
name: mysagra
services:
mysagra-backend:
image: ghcr.io/mysagra/mysagra-backend:latest
container_name: mysagra-api
env_file: .env
ports:
- "4300:4300"
environment:
- NODE_ENV=${NODE_ENV:-production}
- DATABASE_URL=mysql://${DB_USER:-mysagra}:${DB_USER_PASSWORD:-mysagra}@db:3306/${MYSQL_DATABASE:-mysagra}
- JWT_SECRET=${JWT_SECRET}
- PEPPER=${PEPPER}
- ALLOWED_ORIGINS=${ALLOWED_ORIGINS}
- MIGRATE_ON_START=true
- TRUST_PROXY_LEVEL=${TRUST_PROXY_LEVEL:-2}
depends_on:
db:
condition: service_healthy
restart: always
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4300/health"]
interval: 30s
timeout: 3s
retries: 3
volumes:
- api_logs:/app/logs
- api_public:/app/public
tmpfs:
- /tmp
- /run
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
networks:
- mysagra-network
db:
image: mysql:latest
container_name: db
env_file: .env
environment:
MYSQL_ROOT_PASSWORD: ${ROOT_PASSWORD:-rootpassword}
MYSQL_DATABASE: "${MYSQL_DATABASE:-mysagra}"
MYSQL_USER: "${DB_USER:-mysagra}"
MYSQL_PASSWORD: ${DB_USER_PASSWORD:-mysagra}
volumes:
- mysql_data:/var/lib/mysql:delegated
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s
timeout: 5s
retries: 5
ports:
- "3306:3306"
restart: always
cap_drop:
- ALL
cap_add:
- CHOWN
- SETGID
- SETUID
- DAC_OVERRIDE
- NET_BIND_SERVICE
security_opt:
- seccomp=unconfined
user: mysql
networks:
- mysagra-network
myamministratore:
image: ghcr.io/mysagra/mysagra-myamministratore:latest
container_name: myamministratore
restart: always
env_file:
- .env
environment:
- NODE_ENV=${NODE_ENV:-production}
- AUTH_URL=${AUTH_URL_AMMINISTRATORE}
- NODE_EXTRA_CA_CERTS=/app/rootCA.pem
volumes:
- ./rootCA.pem:/app/rootCA.pem:ro
depends_on:
mysagra-backend:
condition: service_healthy
networks:
- mysagra-network
redis:
image: redis:alpine
container_name: redis
command: redis-server --requirepass ${REDIS_PASS}
ports:
- "6379:6379"
volumes:
- redis_data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
restart: always
networks:
- mysagra-network
nginx:
image: nginx:alpine
container_name: mysagra-nginx
restart: always
ports:
- "80:80"
- "443:443"
- "81:81"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./certs:/etc/nginx/certs:ro
networks:
- mysagra-network
depends_on:
- mysagra-backend
- myamministratore
volumes:
api_logs:
driver: local
api_public:
driver: local
mysql_data:
driver: local
redis_data:
driver: local
nginx_certs:
driver: local
networks:
mysagra-network:
driver: bridgeExpected folder structure after this step:
Generate TLS certificates
Use mkcert to create a locally-trusted certificate for your server IP or domain and copy the root CA so the containers trust it.
1 β Install mkcert
Linux (apt)
Linux / macOS (Homebrew)
Windows (winget)
Windows (Scoop)
2 β Install the local CA
This makes your OS and browsers trust the certificate. Run once per machine.
3 β Create the certs folder and generate the certificate
Run from inside your mysagra/ folder. Replace YOUR_SERVER_IP with your actual IP or domain.
Linux / macOS
Windows (PowerShell)
4 β Copy rootCA.pem into the project folder
The containers need this file to trust the self-signed certificate internally.
Linux / macOS
Windows (PowerShell)
Start the stack
From your mysagra/ folder, bring all services up in detached mode.
On first boot MySagra will run database migrations automatically. Check the logs with docker compose logs -f mysagra-backend.
Where to find the services
Once the stack is running, replace SERVER_IP with your actual IP or domain:
| Service | URL |
|---|---|
| MyCassa | https://SERVER_IP (port 443) |
| Admin panel (MyAmministratore) | https://SERVER_IP:81 |
| MyStampa | https://SERVER_IP:3032 |
| MyNumeri | https://SERVER_IP:3033 |
| MyClienti | https://SERVER_IP:3034 |
| DBGate | http://SERVER_IP:3000 |
Trust the certificate on local devices
For a private LAN deployment using a self-signed certificate, every device that needs to access MySagra must trust the rootCA.pem you generated in Step 2. Copy rootCA.pem from your server to the target machine, then install it:
Windows
Alternatively, double-click rootCA.pem, choose Install Certificate β Local Machine β Trusted Root Certification Authorities.
macOS
Linux (Debian / Ubuntu)
On Android go to Settings β Security β Install a certificate β CA certificate and select rootCA.pem. On iOS / iPadOS AirDrop or email yourself the file, tap it to install, then go to Settings β General β VPN & Device Management β Certificate Trust Settings and enable full trust.
Create API keys
Certain services authenticate with the API via API key. Create them in the admin panel before those services can connect.
MyStampa and MyClienti will fail to authenticate with the API until you create and register their API keys. The .env file pre-generates placeholder values in Step 1, but you must create matching keys in the admin panel before the services will work.
How to create API keys
- Open the admin panel at
https://SERVER_IP:81and log in after Step 3 has completed. - Navigate to Settings β API Keys β New key.
- For MyStampa: select type
PRINTER, name itMyStampa, and click Create. - Copy the generated key (starts with
ms_pt_) and paste it into your.envfile as the value forMYSTAMPA_API_KEY. - Repeat for MyClienti: create a
WEBAPPtype key namedMyClienti, copy thems_wb_key, and paste intoMYCLIENTI_API_KEY. - Restart the affected services:
Note: The .env tab in Step 1 pre-generates placeholder values for MYSTAMPA_API_KEY and MYCLIENTI_API_KEY. You can replace them with the real keys after creating them in the admin panel, or regenerate the placeholders if you prefer to use different values.