Installation Guide

SafeCall is a comprehensive location tracking and safety system for enterprises. This guide covers installation, configuration, and management.

Overview

SafeCall consists of:

Server: Core application handling tracking, web interface, and API
Database: SQLite-based storage for beacons, users, and tracking data
Web Interface: Modern web application for management and monitoring
Supporting Services: Optional nginx (SSL), monit (monitoring), and cron (auto-updates)

Installation Architecture

The installer uses a two-phase design:

Phase 1 — install     Phase 2 — setup
────────────────      ──────────────────
Download binary       Guided wizard (6 prompts)
Copy scripts          Configure service
Write default config  Optional: nginx, cron
Print next steps      Run selftest

This separation means Phase 1 is safe to re-run (it only drops files) and Phase 2 can be re-run independently to reconfigure.

Prerequisites

OS: Linux (Ubuntu/Debian recommended)
Architecture: x86_64 or ARM64
Memory: 512MB+ RAM
Storage: 500MB free
Network: Internet connection for downloads
Root access: Required for installation

For pseudo-air-gapped deployments, use the dedicated Offline Installation workflow.

Installation Doctor

If you already have SafeCall installed and want to check whether it needs updating or migrating, use the --doctor flag. It runs from a temporary directory and never modifies your installation until you confirm an action.

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --doctor
curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --doctor --dir /opt/safecall

The doctor detects three scenarios:

Pre-5.x installation (no version.txt or major version < 5): Offers to run a full migration that moves your config and database to the current directory layout while preserving all data.
Outdated 5.x: Shows the installed vs. available version and offers to update.
Up to date: Verifies file integrity via checksums. If files are corrupted, offers to repair.

Quick Start

One-liner (install + setup with defaults)

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --setup

This performs both phases automatically using sensible defaults. The service will be running when it completes.

Two-step (recommended for production)

bash

# Phase 1: Download files
curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s --

# Phase 2: Configure with guided wizard
cd /opt/safecall
sudo ./util.sh system setup

The wizard asks 6 questions (service name, features, port, systemd, nginx, cron) — press Enter to accept each default.

Two-step with all defaults

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s --
cd /opt/safecall
sudo ./util.sh system setup --defaults

Two-Phase Installation

Phase 1: `install`

Downloads the binary, scripts, and writes default configuration (config/main.config.json in current builds). Does not start any services.

bash

# Default directory (/opt/safecall)
curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s --

# Custom directory
curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --dir /custom/path

Files created by Phase 1:

File	Purpose
`safecall`	Main binary
`util.ts`	Bundled TypeScript CLI
`util.sh`	Bash wrapper for CLI
`config/main.config.json`	Default configuration
`version.txt`	Installed version
`checksums.json`	SHA-256 hashes of util.sh and util.ts
`db/`	Database directory

Phase 2: `setup`

Configures the service with a guided wizard or --defaults.

bash

cd /opt/safecall
sudo ./util.sh system setup              # interactive wizard
sudo ./util.sh system setup --defaults   # accept all defaults

Wizard prompts (6 max):

#	Prompt	Default
1	Service name	`safecall`
2	Features	bridge + safecall
3	HTTP port	`8088`
4	Register systemd service?	Yes
5	Setup nginx with SSL?	No
6	Setup automatic updates?	No

What setup does:

Writes config/main.config.json with your choices
Persists .service_name
Creates and starts systemd service (if yes)
Sets up nginx with self-signed SSL (if yes)
Installs daily update cron job (if yes)
Runs system selftest to verify everything works

Commands Reference

All commands require root (sudo). If the CLI symlink is installed, use safecall <command>. Otherwise, use ./util.sh <command> from the install directory.

Command	Description
`system install --dir <dir> [--service-name <name>] [--offline-dir <path>]`	Phase 1: install binary + scripts + default config (online or offline source)
`system setup [--defaults] [--service-name <name>]`	Phase 2: guided wizard to configure service
`config show`	Show current configuration (pretty-printed)
`config edit`	Open config in `$EDITOR` (or nano), restart service
`config set <key> <value>`	Set a single config key, restart service
`config reset`	Reset config to defaults, restart service
`system update [--offline-dir <path>]`	Update binary to latest version (online or offline source)
`system repair --dir <dir> [--migrate] [--offline-dir <path>]`	Reinstall binary/scripts, recreate service. With `--migrate`: also migrate 4.x layout
`system doctor --dir <dir> [--offline-dir <path>]`	Diagnose installation: detect version, check integrity, guide upgrade/migration
`system uninstall`	Completely remove SafeCall (stops service, removes files)
`system selftest`	Run deployment health checks
`dev test [--selftest\|--full\|--clean]`	Run tests (selftest, full VM suite, or cleanup)
`system status`	Show service, monit, cron, and CLI status
`integrations systemd --user <user>`	Create/recreate systemd service
`integrations server --nginx --ip <ip>`	Setup nginx with SSL
`integrations cron`	Setup daily update cron job
`app users create`	Create a new user (interactive)
`app users delete`	Delete a user by email
`app users reset-password`	Reset default admin password
`integrations monit`	Install and configure monit monitoring
`dev generate util-sh`	Regenerate util.sh wrapper

Configuration

Viewing Configuration

bash

# Pretty-printed summary grouped by section
sudo safecall config

# Raw JSON
cat /opt/safecall/config/main.config.json

Editing Configuration

bash

# Open in editor (restarts service after save)
sudo safecall config edit

# Set a single value (restarts service)
sudo safecall config set server_http_port 9090
sudo safecall config set server_features '["safecall"]'

# Reset to defaults (restarts service)
sudo safecall config reset

Configuration Reference

The config/main.config.json file is organized into sections. See the Configuration page for full details.

Service Management

Systemd

bash

sudo systemctl status safecall
sudo systemctl start safecall
sudo systemctl stop safecall
sudo systemctl restart safecall

Health Checks

bash

# Quick selftest (checks files, config, DB, HTTP, service, disk)
sudo safecall system selftest

# Full status overview
sudo safecall system status

Updates

bash

# Manual update
sudo safecall system update

# Automatic daily updates (via cron)
sudo safecall integrations cron

User Management

bash

sudo safecall app users create          # interactive
sudo safecall app users delete          # by email
sudo safecall app users reset-password  # reset admin password

Troubleshooting

Service Won't Start

bash

sudo journalctl -u safecall -f
sudo safecall system selftest
sudo safecall config show

Port Conflicts

bash

ss -tlnp | grep :8088
sudo safecall config set server_http_port 9090

Permission Issues

bash

sudo chown -R root /opt/safecall
sudo safecall integrations systemd --user root

If installer/setup fails with ./util.sh: Permission denied, see the dedicated troubleshooting guide: Installer /tmp noexec issue.

Repair Installation

The repair command re-downloads the binary and scripts while preserving your config and database:

bash

sudo safecall system repair --dir /opt/safecall

If the CLI itself is broken, re-run Phase 1 and then setup:

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s --
cd /opt/safecall
sudo ./util.sh system setup --defaults

Complete Reinstall

bash

# Uninstall
sudo safecall system uninstall

# Fresh install
curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --setup

Migrating from 4.x

If you have an older 4.x installation with the legacy directory layout (config at root, database at root), use system repair --migrate to upgrade to the current structure while preserving your configuration and database:

bash

sudo safecall system repair --dir /opt/safecall --migrate

Or use the doctor to detect and guide the migration automatically:

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --doctor

What migration does:

Moves main.config.json from root to config/main.config.json
Moves safecall.db and sensor_data.db from root to db/
Updates server_db_path in the config to reflect the new location
Removes legacy artifacts (updater.sh in the install directory)
Re-downloads the binary, regenerates scripts, and recreates the systemd service
Writes version.txt and checksums.json
Runs a selftest to verify everything works

All configuration values and database data are preserved.

Daily update cron after migration

system repair --migrate updates layout/files and recreates the service, but it does not set up the optional daily update cron job.

After migration, run:

bash

cd /opt/safecall
sudo safecall integrations cron

If you are invoking through util.sh from the install directory, use:

bash

sudo ./util.sh integrations cron

Verify cron status:

bash

sudo safecall system status

File Integrity

Starting with version 5.12, the installer writes a checksums.json file alongside util.sh and util.ts after every install, update, and repair. This file contains SHA-256 hashes of both utility scripts.

The selftest command verifies these hashes automatically:

bash

sudo safecall system selftest

If a file has been modified or corrupted, selftest reports the mismatch. Use safecall system repair to restore the correct files.

For installations that predate the integrity checking feature, checksums.json will not exist. Selftest will note this as a warning rather than a failure. Running safecall system repair or safecall system update will generate the checksums file.

Multiple Instances

You can run multiple SafeCall instances on the same machine by using different directories, service names, and ports. Each instance gets its own configuration, database, systemd service, and CLI command.

Parameters

Parameter	Description	Default
`--dir <path>`	Installation directory	`/opt/safecall`
`--service-name <name>`	Systemd service name and CLI command name	`safecall`

Example: Two instances on one machine

Install the first instance (defaults):

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- --setup

This installs to /opt/safecall with service name safecall on port 8088.

Install the second instance:

bash

curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- \
  --setup --dir /opt/safecall-second --service-name safecall-second

Change the port on the second instance (to avoid conflict with the first):

bash

sudo safecall-second config set server_http_port 8089

Verify both are running:

bash

sudo systemctl status safecall
sudo systemctl status safecall-second

Step-by-step (without one-liner)

If you prefer the two-step approach for each instance:

bash

# Instance B: Phase 1 (file-drop)
curl -fsSL https://updates.wantok.cz/download/safecall/installer | sudo bash -s -- \
  --dir /opt/safecall-second --service-name safecall-second

# Change to the new directory
cd /opt/safecall-second

# Set a different port before running setup
sudo ./util.sh config set server_http_port 8089

# Instance B: Phase 2 (setup)
sudo ./util.sh system setup --defaults

File layout per instance

Each instance is self-contained in its own directory:

Resource	Instance A (default)	Instance B (custom)
Directory	`/opt/safecall/`	`/opt/safecall-second/`
Config	`/opt/safecall/config/main.config.json`	`/opt/safecall-second/config/main.config.json`
Database	`/opt/safecall/db/safecall.db`	`/opt/safecall-second/db/safecall.db`
Service	`/etc/systemd/system/safecall.service`	`/etc/systemd/system/safecall-second.service`
CLI	`/usr/local/bin/safecall`	`/usr/local/bin/safecall-second`
Port	`8088`	`8089` (user-configured)

Managing individual instances

Use each instance's CLI command (the service name) for management:

bash

sudo safecall system status           # first instance
sudo safecall-second system status    # second instance

sudo safecall system update           # update first
sudo safecall-second system update    # update second

sudo safecall-second system uninstall # remove second instance only

Advanced Usage

Custom Service User

bash

sudo useradd -r -s /bin/false safecall
sudo safecall integrations systemd --user safecall

Nginx with Custom IP

bash

sudo safecall integrations server --nginx --ip 192.168.1.100

Subpath Deployment (Reverse Proxy)

SafeCall can be served behind a subpath (e.g. https://example.com/safecall/app/) instead of the domain root. The frontend uses relative URLs, so no rebuild is required. Only the reverse proxy needs to strip the prefix:

nginx

# Option A: trailing slash on proxy_pass strips the prefix automatically
location /safecall/app/ {
    proxy_read_timeout 300s;
    proxy_connect_timeout 75s;
    proxy_pass http://127.0.0.1:8088/;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

# Redirect /safecall/app (no trailing slash) to /safecall/app/
location = /safecall/app {
    return 301 /safecall/app/;
}

The key detail is the trailing slash on proxy_pass http://127.0.0.1:8088/; — this tells nginx to replace the matched /safecall/app/ prefix with /, so the backend receives requests at its expected root paths.

WARNING

Without the trailing slash, nginx forwards the full path (e.g. /safecall/app/version) to the backend, which doesn't have routes at those paths and returns a "Not found" error.

Firewall

bash

sudo ufw allow 8088/tcp   # HTTP
sudo ufw allow 443/tcp    # HTTPS (with nginx)

File Locations

File	Location	Purpose
Binary	`/opt/safecall/safecall`	Main application
Config	`/opt/safecall/config/main.config.json`	Configuration
Database	`/opt/safecall/db/safecall.db`	Data storage
Service	`/etc/systemd/system/safecall.service`	Systemd unit
CLI	`/usr/local/bin/safecall`	Symlink to util.sh
Service name	`/opt/safecall/.service_name`	Persisted service name
Version	`/opt/safecall/version.txt`	Installed version
Checksums	`/opt/safecall/checksums.json`	SHA-256 hashes for integrity checking

Installation Guide ​

Overview ​

Installation Architecture ​

Prerequisites ​

Installation Doctor ​

Quick Start ​

One-liner (install + setup with defaults) ​

Two-step (recommended for production) ​

Two-step with all defaults ​

Two-Phase Installation ​

Phase 1: install ​

Phase 2: setup ​

Commands Reference ​

Configuration ​

Viewing Configuration ​

Editing Configuration ​

Configuration Reference ​

Service Management ​

Systemd ​

Health Checks ​

Updates ​

User Management ​

Troubleshooting ​

Service Won't Start ​

Port Conflicts ​

Permission Issues ​

Repair Installation ​

Complete Reinstall ​

Migrating from 4.x ​

Daily update cron after migration ​

File Integrity ​

Multiple Instances ​

Parameters ​

Example: Two instances on one machine ​

Step-by-step (without one-liner) ​

File layout per instance ​

Managing individual instances ​

Advanced Usage ​

Custom Service User ​

Nginx with Custom IP ​

Subpath Deployment (Reverse Proxy) ​

Firewall ​

File Locations ​

Installation Guide

Overview

Installation Architecture

Prerequisites

Installation Doctor

Quick Start

One-liner (install + setup with defaults)

Two-step (recommended for production)

Two-step with all defaults

Two-Phase Installation

Phase 1: `install`

Phase 2: `setup`

Commands Reference

Configuration

Viewing Configuration

Editing Configuration

Configuration Reference

Service Management

Systemd

Health Checks

Updates

User Management

Troubleshooting

Service Won't Start

Port Conflicts

Permission Issues

Repair Installation

Complete Reinstall

Migrating from 4.x

Daily update cron after migration

File Integrity

Multiple Instances

Parameters

Example: Two instances on one machine

Step-by-step (without one-liner)

File layout per instance

Managing individual instances

Advanced Usage

Custom Service User

Nginx with Custom IP

Subpath Deployment (Reverse Proxy)

Firewall

File Locations