Remote Installation Guide

Overview

The SPEAR remote installer provides a streamlined, production-ready deployment experience through a single command. The installer is a two-stage system: a bootstrap script (install.sh) that validates your environment and downloads the release, and an orchestrator script (setup.sh) that handles installation, verification, and optional post-install configuration.

Key benefits:

• Pre-flight validation — Checks disk, memory, CPU, network, and port availability before starting
• Multiple installation modes — Quick, Production, Development, Config File, and Non-Interactive
• Automatic rollback — Backs up existing installations and restores on failure
• State persistence — Resume interrupted installations within 1 hour
• Installation verification — Health check polling with retry logic
• Telemetry — Anonymous, opt-out metrics for reliability tracking
• Multi-server support — Bulk deployment via CSV with parallel execution
• Clean uninstallation — Full removal with optional data backup

Architecture

The installation process works as follows:

1. User runs install command - Downloads and executes the installer
2. Pre-flight checks - System validates requirements (disk, memory, network, etc.)
3. Download release - Fetches the SPEAR binary from the Vault server
4. Backup existing - If upgrading, backs up the current installation
5. Install binary - Copies SPEAR to the installation directory
6. Create service - Sets up the systemd service
7. Start service - Enables and starts SPEAR
8. Health check - Verifies the installation is working
9. Generate report - Creates installation summary (on success) or triggers rollback (on failure)

Prerequisites

System Requirements

Requirement	Minimum	Recommended	Severity
Operating System	Linux with systemd	Ubuntu 22.04+ / Debian 12+	Required
Architecture	amd64, arm64, or armv7	amd64	Required
Disk Space	2 GB free in /opt	5 GB+	Required
Memory (RAM)	1 GB	2 GB+	Warning
CPU Cores	1	2+	Warning
Network	Connectivity to vault.spear.vtemlabs.com	—	Required
Port	8090 (default) available	—	Warning

Required Dependencies

Dependency	Purpose	Check
curl	Downloading installer and release	which curl
tar	Extracting release tarball	which tar
systemctl	Service management	which systemctl

Supported Architectures

System Architecture	Mapped Platform
x86_64 / amd64	linux-amd64
aarch64 / arm64	linux-arm64
armv7l / armhf	linux-arm

License Key

A valid SPEAR license key is required. Obtain your license key from the SPEAR Vault portal.

Quick Start

Standard Installation

curl -sSL https://install.spear.vtemlabs.com | sudo bash

You will be prompted for your license key (input is hidden).

With Pre-Set License Key

curl -sSL https://install.spear.vtemlabs.com | sudo LICENSE_KEY=your-key bash

Verify Installation

After installation completes:

# Check service status
sudo systemctl status spear

# Check health endpoint
curl -s http://localhost:8090/api/health

# View installation report
cat /var/lib/spear/installation-report.txt

Access Points

Service	URL
SPEAR Application	http://localhost:8090
Health Check	http://localhost:8090/api/health
Admin Panel	http://localhost:8090/_/

Installation Modes

Mode Comparison

Feature	Quick	Production	Development	Non-Interactive	Default
Interactive prompts	No	Yes (full)	No	No	Yes
Auto port selection	Yes (8090-8099)	Suggest if busy	Yes (8090-8099)	No (uses 8090)	No
SSL recommendation	Auto-detect	Strongly recommended	Forced none	Uses default	Prompted
Encryption key	Auto-generated	32-char enforced	Auto-generated	Auto-generated	Prompted
Verbose logging	No	No	Yes (debug)	No	No
Confirmation step	No	Yes	No	No	No
Post-install wizard	No	Yes	No	No	Yes
Best for	CI/CD, scripting	Live servers	Local testing	Automated deploys	First-time

Quick Mode

Minimal prompts with smart defaults. Auto-selects an available port from 8090-8099 and detects SSL mode from domain.

curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --quick

Production Mode

Full interactive setup with security-focused defaults. SSL is strongly recommended, and encryption keys must be exactly 32 characters.

curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --production

Development Mode

Non-interactive with verbose logging. Forces SSL to none and sets SPEAR_LOG_LEVEL=debug in the systemd service.

curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --development

Non-Interactive Mode

Uses all defaults without prompting. Suitable for automation scripts.

curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --non-interactive
# or
curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- -y

Configuration File Support

The installer supports loading settings from a configuration file using simple KEY=VALUE format.

Usage

# With explicit config file
curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --config /etc/spear/install.conf

# Auto-loaded from default location (if present)
# The installer checks /etc/spear/install.conf automatically

Available Options

Key	Type	Default	Description
LICENSE_KEY	string	(required)	SPEAR license key
PORT	number	8090	HTTP listening port (1-65535)
DOMAIN	string	(empty)	Domain name for SSL configuration
SSL_MODE	string	none	SSL mode: none, letsencrypt, or traefik
INSTALL_DIR	path	/opt/spear	Binary installation directory
DATA_DIR	path	/var/lib/spear	Data storage directory
ENCRYPTION_KEY	string	auto-generate	16/24/32 character key, or auto-generate
SKIP_PROMPTS	boolean	false	Skip interactive prompts (true/yes/1)
TELEMETRY_ENABLED	boolean	true	Enable anonymous telemetry

Precedence Rules

1. CLI arguments (highest priority)
2. Config file (specified via --config)
3. Auto-loaded config (/etc/spear/install.conf if present)
4. Defaults (lowest priority)

Example Configurations

Production Server:

LICENSE_KEY=SPEAR-PROD-xxxx-xxxx-xxxx
PORT=8090
DOMAIN=spear.company.com
SSL_MODE=letsencrypt
INSTALL_DIR=/opt/spear
DATA_DIR=/var/lib/spear
ENCRYPTION_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
SKIP_PROMPTS=true
TELEMETRY_ENABLED=true

Staging Server:

LICENSE_KEY=SPEAR-STG-xxxx-xxxx-xxxx
PORT=9090
DOMAIN=spear-staging.company.com
SSL_MODE=traefik
ENCRYPTION_KEY=auto-generate
SKIP_PROMPTS=true

Development Server:

LICENSE_KEY=SPEAR-DEV-xxxx-xxxx-xxxx
PORT=8090
SSL_MODE=none
ENCRYPTION_KEY=auto-generate
SKIP_PROMPTS=true
TELEMETRY_ENABLED=false

Security

Config files may contain license keys. Set file permissions to chmod 600 to restrict access:

sudo chmod 600 /etc/spear/install.conf
sudo chown root:root /etc/spear/install.conf

Pre-Flight System Checks

The bootstrap script performs comprehensive system validation before downloading anything.

Comprehensive Checks

Check	Requirement	Severity	Action on Failure
Root privileges	UID 0	Fatal	Exit with instructions
Operating system	Linux	Fatal	Exit with error
Architecture	amd64, arm64, or arm	Fatal	Exit with error
curl available	In PATH	Fatal	Exit with install hint
tar available	In PATH	Fatal	Exit with install hint
systemctl available	In PATH	Fatal	Exit with error
Disk space	>= 2 GB in /opt	Fatal	Exit with current usage
Memory	>= 2 GB RAM	Warning	Continue with warning
CPU cores	>= 2 cores	Warning	Continue with warning
Network connectivity	Can reach Vault server	Fatal	Exit + collect diagnostics
Port 8090	Not in use	Warning	Continue with warning
lsof available	In PATH	Warning	Port process identification skipped

Resolving Common Pre-Flight Failures

Disk space: Free space in /opt or choose a different installation directory via the INSTALL_DIR config option.

Memory warning: The installer will continue, but performance may be limited on systems with less than 2 GB RAM.

Port conflicts: If port 8090 is in use, the installer warns you. Use --port to specify an alternative, or use Quick/Development mode which auto-selects an available port in the 8090-8099 range.

Missing dependencies: Install the required packages for your distribution:

# Debian/Ubuntu
sudo apt-get install -y curl tar

# RHEL/CentOS
sudo yum install -y curl tar

# Fedora
sudo dnf install -y curl tar

Installation Process

Step-by-Step Breakdown

Step	Name	Action
1	user_created	Creates spear system user (no home, no login shell)
2	directories_created	Creates /opt/spear, /var/lib/spear, /var/log/spear (mode 750)
3	binary_installed	Copies SPEAR binary to /opt/spear/spear (mode 755)
4	service_created	Creates systemd service at /etc/systemd/system/spear.service
5	service_started	Enables and starts the SPEAR service

Progress Indicators

The installer displays visual progress during installation:

• Step counters (e.g., [2/5] Creating directories...)
• Color-coded output (green for success, red for errors, yellow for warnings)
• A progress bar with percentage completion

Installation Duration

Typical installation completes in under 2 minutes, depending on network speed for the binary download. The installer tracks duration and reports it on completion.

Verification and Health Checks

Automatic Verification

After starting the service, the installer automatically verifies the installation by polling the health endpoint:

• Endpoint: http://localhost:{PORT}/api/health
• Retries: 30 attempts
• Interval: 2 seconds between attempts
• Total timeout: 60 seconds
• Pre-check: Verifies service is running via systemctl is-active

What Happens on Verification Failure

If the health check does not pass within the timeout period:

1. The installer logs the failure with details
2. Automatic rollback is triggered (if a backup exists)
3. The previous SPEAR version is restored and restarted
4. The state file is preserved so you can retry

Manual Verification

# Check service status
sudo systemctl status spear

# Check health endpoint
curl -s http://localhost:8090/api/health

# View recent logs
sudo journalctl -u spear --since "5 minutes ago" --no-pager

# Check port binding
sudo ss -tlnp | grep 8090

Automatic Rollback

When Rollback Is Triggered

Rollback activates automatically when the installation fails after modifying the system (e.g., binary installed but service fails to start, or health check times out).

What Gets Rolled Back

Component	Action
Binary	Previous binary restored from backup
Service file	Previous systemd unit file restored
Configuration	Previous install info restored
Service	Previous version restarted

Backup Location

Backups are stored at {INSTALL_DIR}/backup-YYYYMMDD_HHMMSS/ (e.g., /opt/spear/backup-20260206_143022/).

Manual Rollback Procedure

If automatic rollback fails:

# List available backups
ls /opt/spear/backup-*/

# Restore binary manually
sudo cp /opt/spear/backup-<timestamp>/spear /opt/spear/spear
sudo chmod 755 /opt/spear/spear

# Restore service file
sudo cp /opt/spear/backup-<timestamp>/spear.service /etc/systemd/system/

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart spear

Installation Resume Capability

State Persistence

If an installation is interrupted, the installer saves progress to a state file so you can resume later.

• State file: /tmp/spear-install-state
• Valid for: 1 hour from last update
• Contents: Completed step, license key, platform, timestamp, all configuration values
• Auto-resume: Set RESUME_INSTALLATION=true environment variable

Resuming a Failed Installation

# Interactive resume (will prompt to resume or start fresh)
curl -sSL https://install.spear.vtemlabs.com | sudo bash

# Automatic resume (non-interactive)
curl -sSL https://install.spear.vtemlabs.com | sudo env RESUME_INSTALLATION=true bash

When to Start Fresh vs Resume

Scenario	Action
State file less than 1 hour old	Resume (prompted or automatic)
State file older than 1 hour	Start fresh (old state is unreliable)
Different server or configuration	Delete state file and start fresh
Corrupted state file	Delete state file and start fresh

To force a fresh installation:

sudo rm -f /tmp/spear-install-state

Post-Installation Configuration Wizard

In interactive modes (Default, Production), the installer offers an optional configuration wizard after installation.

Available Configurations

Service	Description	Config File
SMTP	Email sending with provider presets (Gmail, Office 365, SendGrid, custom)	{DATA_DIR}/smtp-config.json
Backups	Automated backup schedules (hourly, daily, weekly, custom cron)	{DATA_DIR}/backup-config.json
SSO/OAuth2	Single sign-on with Google, Azure AD, GitHub, GitLab, custom OAuth2, or SAML	{DATA_DIR}/sso-config.json

Skipping the Wizard

The wizard is automatically skipped in Quick, Development, and Non-Interactive modes. All features configured by the wizard can also be set up later through the SPEAR web UI.

Installation Telemetry

What Data Is Collected

The installer sends a single anonymous telemetry event upon successful installation:

Field	Example	Purpose
event	installation_complete	Event type
platform	linux-amd64	Target platform
os	Linux	Operating system
arch	x86_64	CPU architecture
installer_version	1.0	Installer version
ssl_mode	letsencrypt	SSL configuration
duration_seconds	45	Installation duration
timestamp	2026-01-15T10:30:00Z	Event timestamp

Privacy

• Anonymous: No personal data, license keys, domain names, or IP-identifying information is included
• IP address: Used server-side for rate limiting only, not stored with telemetry data
• Non-blocking: Telemetry is sent in the background and never delays or fails the installation
• Rate limited: 10 events per IP per hour

How to Opt-Out

# Via environment variable
curl -sSL https://install.spear.vtemlabs.com | sudo env TELEMETRY_ENABLED=false bash

# Via config file
TELEMETRY_ENABLED=false

Installation Reports

Report Location

After successful installation, a detailed report is generated at:

/var/lib/spear/installation-report.txt

Report Contents

• System information (hostname, OS, architecture, timezone)
• Configuration details (port, domain, SSL mode, directories)
• Service status
• Health check result
• Next steps for accessing the admin UI

Viewing the Report

cat /var/lib/spear/installation-report.txt

Installation metadata is also saved to /var/lib/spear/.spear-install-info for internal reference.

Multi-Server Deployment

For deploying SPEAR across multiple servers, use the multi-deploy.sh tool.

CSV File Format

server,license-key,domain[,port][,ssl-mode]
prod-1.example.com,SPEAR-PROD-xxxx,spear.example.com,8090,letsencrypt
dev-1.example.com,SPEAR-DEV-xxxx,dev.example.com

Deployment Modes

Mode	Flag	Default Concurrency	Best For
Sequential	(default)	1	Production, debugging
Parallel	--parallel	3 (configurable)	Large-scale rollouts

Usage

# 1. Create server list from example
cp servers.example.csv servers.csv

# 2. Edit with your server details
vim servers.csv

# 3. Validate with dry run
./multi-deploy.sh --file servers.csv --dry-run

# 4. Deploy sequentially (safer)
./multi-deploy.sh --file servers.csv --ssh-key ~/.ssh/deploy_key

# 5. Or deploy in parallel (faster)
./multi-deploy.sh --file servers.csv --ssh-key ~/.ssh/deploy_key --parallel --concurrency 5

Multi-Deploy Options

Option	Default	Description
--file FILE	(required)	CSV server list
--parallel	Sequential	Enable parallel deployment
--concurrency N	3	Max parallel deployments
--dry-run	—	Validate and show plan only
--ssh-user USER	root	SSH username
--ssh-key PATH	System default	SSH private key
--timeout SECONDS	600	Timeout per server

A deployment summary report is generated after completion, detailing the status of each server.

Uninstallation

The uninstall.sh script safely removes SPEAR with optional data backup.

Usage

# Interactive uninstall (recommended - includes backup)
sudo ./uninstall.sh

# Automated uninstall (skip confirmation, still backs up data)
sudo ./uninstall.sh --force

# Fast uninstall (no backup - not recommended for production)
sudo ./uninstall.sh --force --no-backup

What Gets Removed

Item	Path	Notes
Systemd service	/etc/systemd/system/spear.service	Stopped, disabled, removed
Installation directory	/opt/spear	Binary and configuration
Data directory	/var/lib/spear	Database, uploads, configs
Log directory	/var/log/spear	Application logs
System user	spear	Service account

Data Backup

By default, the data directory is backed up before removal:

• Backup location: /var/lib/spear-backup-YYYYMMDD_HHMMSS
• Contents: Complete copy of /var/lib/spear
• Skip backup: --no-backup flag (not recommended)

Restore After Uninstall

sudo mkdir -p /var/lib/spear
sudo cp -a /var/lib/spear-backup-<timestamp>/. /var/lib/spear/
sudo chown -R spear:spear /var/lib/spear

Advanced Usage Examples

Interactive Installation Walkthrough

# Download and run installer (will prompt for license key)
curl -sSL https://install.spear.vtemlabs.com | sudo bash

# Follow the prompts:
# 1. Enter license key
# 2. Choose port (default: 8090)
# 3. Enter domain (optional, for SSL)
# 4. Select SSL mode (1=Let's Encrypt, 2=Traefik, 3=None)
# 5. Choose installation directory (default: /opt/spear)
# 6. Choose data directory (default: /var/lib/spear)
# 7. Enter or auto-generate encryption key
# 8. Configure SMTP, backups, SSO (optional)

Production Deployment with Config File

# Create config file
sudo mkdir -p /etc/spear
cat <<EOF | sudo tee /etc/spear/install.conf
LICENSE_KEY=SPEAR-PROD-xxxx-xxxx-xxxx
PORT=8090
DOMAIN=spear.company.com
SSL_MODE=letsencrypt
ENCRYPTION_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
SKIP_PROMPTS=true
EOF
sudo chmod 600 /etc/spear/install.conf

# Install with production mode
curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --production --config /etc/spear/install.conf

Development Setup

# Auto-selects port, disables SSL, enables debug logging
curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --development

Quick Testing Installation

# Minimal prompts, smart defaults, auto port selection
curl -sSL https://install.spear.vtemlabs.com | sudo LICENSE_KEY=your-key bash -s -- --quick

Upgrade Existing Installation

# The installer automatically backs up the existing installation before upgrading.
# If the upgrade fails, it rolls back to the previous version.
curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --config /etc/spear/install.conf

Resume Failed Installation

# Automatically resume if state file exists and is valid (< 1 hour old)
curl -sSL https://install.spear.vtemlabs.com | sudo env RESUME_INSTALLATION=true bash

Multi-Server Deployment

# Prepare server list and deploy in parallel
cp servers.example.csv production-servers.csv
vim production-servers.csv

./multi-deploy.sh --file production-servers.csv --ssh-key ~/.ssh/deploy --parallel --concurrency 5

Troubleshooting

Download Errors

HTTP Code	Meaning	Resolution
401 / 403	License authentication failed	Verify license key at your account portal. Check for typos. Ensure the license is not revoked or expired.
404	Platform not found	Your platform may not have a published binary. Contact support.
429	Rate limit exceeded	Wait approximately 15 minutes and retry.
000	Connection failed	Check network connectivity to vault.spear.vtemlabs.com. Verify DNS resolution. Check firewall rules.
5xx	Server error	Vault server may be temporarily unavailable. Retry in a few minutes. Check diagnostics file.

Pre-Flight Check Failures

Check	Error	Resolution
Root	”This installer must be run as root”	Run with sudo
Disk space	”Insufficient disk space”	Free space in /opt (need 2 GB+)
Network	”Cannot reach Vault server”	Check DNS, firewall, and proxy settings
Dependencies	”curl/tar/systemctl not found”	Install missing package: apt install curl or yum install curl

Verification Failures

If the health check fails after installation:

# 1. Check service status
sudo systemctl status spear

# 2. Check logs
sudo journalctl -u spear --no-pager -n 100

# 3. Check port binding
sudo lsof -i :8090

# 4. Manual health check
curl -v http://localhost:8090/api/health

# 5. Check permissions
ls -la /opt/spear/ /var/lib/spear/

Rollback Issues

If automatic rollback fails:

# 1. Check if backup exists
ls /opt/spear/backup-*/

# 2. Manually restore binary
sudo cp /opt/spear/backup-*/spear /opt/spear/spear

# 3. Restore service file
sudo cp /opt/spear/backup-*/spear.service /etc/systemd/system/

# 4. Reload and restart
sudo systemctl daemon-reload && sudo systemctl restart spear

Port Conflicts

# Check what's using port 8090
sudo lsof -i :8090
# or
sudo ss -tlnp | grep 8090

# Use a different port during installation
curl -sSL https://install.spear.vtemlabs.com | sudo bash -s -- --port 9090

Permission Errors

# Fix directory ownership
sudo chown -R spear:spear /opt/spear /var/lib/spear /var/log/spear

# Fix directory permissions
sudo chmod 750 /opt/spear /var/lib/spear /var/log/spear

# Fix binary permissions
sudo chmod 755 /opt/spear/spear

SSL Configuration Issues

Issue	Resolution
Let’s Encrypt fails	Ensure ports 80/443 are open and domain DNS points to the server
Certificate renewal	SPEAR handles auto-renewal. Check logs if failing.
Behind Traefik	Use --ssl traefik and configure Traefik separately. See Traefik SSL.

State/Resume Issues

Issue	Resolution
State file not found	No previous installation to resume. Start fresh.
State expired (> 1 hour)	Start a fresh installation. Old state is unreliable.
State file corrupted	Delete /tmp/spear-install-state and start fresh.

Diagnostics Collection

When fatal errors occur (network failures, server errors), the installer automatically collects diagnostics and saves them to /tmp/spear-install-diagnostics-YYYYMMDD_HHMMSS.txt.

Collected information:

• CPU info and core count
• Memory info (free -h)
• Disk usage (df -h /opt)
• Port 8090 usage
• SPEAR service status
• Recent journal logs

Getting Support

When contacting support, include:

1. Diagnostics file: /tmp/spear-install-diagnostics-*.txt (auto-generated on failure)
2. Installation report: /var/lib/spear/installation-report.txt
3. Service logs: sudo journalctl -u spear --no-pager -n 200
4. System info: OS version, architecture, available disk/memory

Contact: [email protected]

Acceptance Criteria

A successful SPEAR installation must satisfy all of the following pass conditions:

Criteria	Verification	Pass Condition
Service active	sudo systemctl is-active spear	Returns active
Health check OK	curl -s http://localhost:{PORT}/api/health	Returns HTTP 200 with valid response
Installation report generated	cat /var/lib/spear/installation-report.txt	File exists and contains system info, configuration, and status
Rollback works on failure	Simulate failure during upgrade	Previous version is restored and service returns to active state

Additional pass conditions for specific modes:

• Production mode: SSL recommendation is presented, encryption key is validated as 32 characters, confirmation step is shown
• Config file mode: All values from the config file are applied correctly and override defaults
• Multi-server mode: Deployment summary report is generated with per-server status

Testing Matrix

The following scenarios should be validated to ensure installer reliability:

Supported OS and Architectures

OS / Distribution	Architecture	Status
Ubuntu 22.04+	amd64	Supported
Ubuntu 22.04+	arm64	Supported
Debian 12+	amd64	Supported
Debian 12+	arm64	Supported
RHEL 9+ / CentOS Stream 9+	amd64	Supported
Any Linux with systemd	armv7	Supported

Installation Modes

Scenario	Command / Config	Expected Outcome
Quick mode	--quick	Auto-selects port, minimal prompts, service active
Production mode	--production	Full prompts, SSL recommendation, 32-char key enforced
Development mode	--development	No prompts, SSL forced to none, debug logging enabled
Non-interactive mode	--non-interactive / -y	All defaults applied, no prompts, service active
Config file install	--config /etc/spear/install.conf	All config values applied, overrides defaults

Resilience and Recovery

Scenario	Steps	Expected Outcome
Resume after interruption	Kill installer mid-install, re-run within 1 hour	Resumes from last completed step
Rollback on verification failure	Install with a corrupted binary or blocked port	Automatic rollback restores previous version
Expired state file	Wait > 1 hour after interruption, re-run	Fresh installation starts (old state discarded)

Telemetry

Scenario	Config	Expected Outcome
Telemetry enabled (default)	No opt-out set	Anonymous event sent on success, installation not delayed
Telemetry disabled	TELEMETRY_ENABLED=false	No telemetry event sent, installation completes normally

Multi-Server Deployment

Scenario	Command	Expected Outcome
Sequential deployment	./multi-deploy.sh --file servers.csv	Servers deployed one at a time, summary report generated
Parallel deployment	./multi-deploy.sh --file servers.csv --parallel --concurrency 5	Up to 5 servers deployed simultaneously, summary report generated
Dry run validation	./multi-deploy.sh --file servers.csv --dry-run	Plan displayed, no changes made to any server

Reference

File Locations

File	Path	Purpose
Install script	curl -sSL https://install.spear.vtemlabs.com	Bootstrap installer
Setup script	Extracted from release tarball	Installation orchestrator
Config file	/etc/spear/install.conf	Auto-loaded configuration
State file	/tmp/spear-install-state	Resume state (temporary, 1 hour)
Install report	/var/lib/spear/installation-report.txt	Human-readable report
Install info	/var/lib/spear/.spear-install-info	Installation metadata
Diagnostics	/tmp/spear-install-diagnostics-*.txt	Error diagnostics
Binary	/opt/spear/spear	SPEAR executable
Service file	/etc/systemd/system/spear.service	Systemd unit
Data directory	/var/lib/spear	Database, uploads, config
Log directory	/var/log/spear	Application logs
SMTP config	/var/lib/spear/smtp-config.json	Email configuration
Backup config	/var/lib/spear/backup-config.json	Backup schedule
SSO config	/var/lib/spear/sso-config.json	SSO/OAuth2 settings

Environment Variables

Variable	Used By	Description
LICENSE_KEY	install.sh	Pre-set license key (skip prompt)
SKIP_VERSION_CHECK	install.sh	Set true to skip version check
TELEMETRY_ENABLED	setup.sh	Set false to disable telemetry
RESUME_INSTALLATION	setup.sh	Set to any value to auto-resume
SPEAR_LICENSE_KEY	setup.sh	License key (set by install.sh)
SPEAR_INSTALL_SOURCE	setup.sh	Source directory (set by install.sh)
SPEAR_CONFIG_FILE	setup.sh	Config file path (set by install.sh)
SPEAR_LOG_LEVEL	systemd service	Set to debug in development mode
VAULT_URL	All scripts	Override Vault server URL

CLI Arguments — install.sh

Argument	Description
--config FILE	Load configuration from file
--skip-version-check	Skip querying Vault for latest version

CLI Arguments — setup.sh

Argument	Description
--from-installer	Marks execution from install.sh (internal)
--config FILE	Load configuration from file
--port PORT	Set SPEAR listening port
--domain DOMAIN	Set domain for SSL
--ssl MODE	SSL mode: none, letsencrypt, traefik
--install-dir DIR	Installation directory
--data-dir DIR	Data directory
--encryption-key KEY	32-character encryption key
--quick	Quick mode (minimal prompts, smart defaults)
--production	Production mode (full prompts, security-focused)
--development	Development mode (no prompts, debug logging)
--non-interactive / -y	Use defaults without prompting
--help / -h	Show help

Exit Codes

Script	Code	Meaning
install.sh	0	Success
install.sh	1	Fatal error (see diagnostics)
setup.sh	0	Success
setup.sh	1	Installation failed (rollback attempted)
uninstall.sh	0	Success (or SPEAR not installed)
uninstall.sh	1	Uninstall failed
multi-deploy.sh	0	All deployments succeeded
multi-deploy.sh	1	One or more deployments failed

Security Best Practices

License Key Protection

• Never commit license keys to version control
• Use config files with chmod 600 permissions for automated deployments
• Use environment variables for CI/CD pipelines
• Hidden input: The interactive prompt hides license key input (stty -echo)

Config File Permissions

sudo chmod 600 /etc/spear/install.conf
sudo chown root:root /etc/spear/install.conf

SSH Key Authentication (Multi-Server)

• Use dedicated SSH keys for deployment (not personal keys)
• Restrict SSH keys to specific commands if possible
• Use a dedicated deployment user with minimal permissions
• Set chmod 600 on CSV files containing license keys

Network Security

• Firewall: Only expose the SPEAR port (default 8090) to required networks
• SSL: Use Let’s Encrypt or Traefik for production deployments
• Port restrictions: Change from the default port in production if desired

Systemd Service Hardening

The generated systemd service includes security hardening by default:

Setting	Value	Purpose
NoNewPrivileges	true	Prevents privilege escalation
PrivateTmp	true	Isolated temporary directory
ProtectSystem	strict	Read-only filesystem (except explicit paths)
ProtectHome	true	No access to home directories
ReadWritePaths	data, log, install dirs	Explicit whitelist for writable directories

Audit Logging

All installation-related events are logged:

• License validation attempts (success/failure) on the Vault server
• Binary downloads with IP and license info
• Telemetry events (anonymous)
• Multi-deploy per-server logs in /tmp/spear-multi-deploy-*/

Next Steps

• Quick Deploy — Build-from-source deployment with systemd
• Traefik SSL — Configure Traefik reverse proxy with SSL
• Environment Variables — Full environment variable reference
• Installer README — Detailed installer script documentation and developer reference
• Set up automated backups via the Admin panel
• Configure branding and RBAC in the admin UI