Quick Deploy

Overview

SPEAR provides multiple deployment options to suit different environments - from simple single-server deployments to production setups with SSL termination via Traefik. This guide covers the essential deployment workflows.

Prerequisites

Before deploying SPEAR, ensure your system meets these requirements:

Requirement	Version	Notes
Node.js	18+	For building the frontend
pnpm	8+	Package manager
Go	1.23.3+	For building the backend
SPEAR_ENCRYPTION_KEY	-	16, 24, or 32 characters

The encryption key is required and used for AES encryption of sensitive data such as API keys.

Quick Deploy Method

The simplest way to deploy SPEAR is using the wrapper script:

sudo ./scripts/deploy.sh --version "1.0.0"

This script handles the entire deployment process including building, service creation, and startup.

Security Warning: Default Encryption Key

The deploy.sh wrapper script sets a hardcoded default encryption key intended only for local testing. Never use this in production.

Before running deploy.sh, export a secure custom key:

# Generate a secure 32-character key
export SPEAR_ENCRYPTION_KEY=$(openssl rand -base64 24)

# Or set your own 16, 24, or 32-character key
export SPEAR_ENCRYPTION_KEY="your-secure-production-key-here"

# Then run deploy
sudo -E ./scripts/deploy.sh --version "1.0.0"

The -E flag preserves your environment variables when running with sudo.

Alternatively, pass the key directly via the --key flag:

sudo ./scripts/deploy.sh --version "1.0.0" --key "your-secure-production-key-here"

Advanced Deploy Method

For more control over the deployment, use the full build-and-deploy script:

sudo ./scripts/build-and-deploy.sh [OPTIONS]

Required: UPDATER_PUBLIC_KEY

The build-and-deploy.sh script requires the UPDATER_PUBLIC_KEY environment variable to be set. This key is embedded in the binary for verifying update signatures.

Extract from your private signing key:

# Extract the public key from your Ed25519 private key
export UPDATER_PUBLIC_KEY=$(go run scripts/extract-public-key.go "$PRIVATE_KEY_B64")

Full deployment command with all required variables:

# Set required environment variables
export SPEAR_ENCRYPTION_KEY="your-secure-32-char-key-here!!"
export UPDATER_PUBLIC_KEY=$(go run scripts/extract-public-key.go "$PRIVATE_KEY_B64")

# Run deployment
sudo -E ./scripts/build-and-deploy.sh -v "1.0.0" -p 8090

Without UPDATER_PUBLIC_KEY, the backend build will fail with an error.

Available Options

Option	Description	Default
-v, --version VERSION	Set the software version	Timestamp
-k, --key ENCRYPTION_KEY	Set the encryption key	From env or default
-p, --port PORT	Set the service port	8090
-u, --user USER	Set the service user	spear
-d, --install-dir DIR	Set installation directory	/opt/spear
--data-dir DIR	Set data directory	/var/lib/spear
--skip-frontend	Skip frontend build	-
--skip-backend	Skip backend build	-
--skip-service	Skip service creation/update	-
--dry-run	Preview actions without executing	-

Examples

# Deploy with specific version and port
sudo ./scripts/build-and-deploy.sh -v "1.0.0" -p 8090

# Skip frontend rebuild, update version only
sudo ./scripts/build-and-deploy.sh --skip-frontend --version "1.0.1"

# Preview deployment actions
sudo ./scripts/build-and-deploy.sh --dry-run

Production Build

For cross-platform binary distribution, use the release build script:

./scripts/build-release.sh v1.0.0

This generates binaries for all supported platforms:

Platform	Architectures
Linux	amd64, arm64, arm
Windows	amd64, arm64
macOS	amd64, arm64

Service Management

After deployment, SPEAR runs as a systemd service. Use these commands to manage it:

# Check service status
sudo systemctl status spear

# View real-time logs
sudo journalctl -u spear -f

# Restart the service
sudo systemctl restart spear

# Stop the service
sudo systemctl stop spear

# Start the service
sudo systemctl start spear

# Enable auto-start on boot
sudo systemctl enable spear

Installation Paths

The deployment script installs SPEAR to these default locations:

Component	Path
Install Directory	/opt/spear
Data Directory	/var/lib/spear
Log Directory	/var/log/spear
Binary	/opt/spear/spear
Service File	/etc/systemd/system/spear.service

First-Time Setup

After deployment:

1. Navigate to the PocketBase admin UI at http://localhost:8090/_/
2. Create your admin account
3. Configure initial settings (branding, RBAC, etc.)

Access Points

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

Troubleshooting

Port Conflicts

If port 8090 is already in use:

# Check what's using the port
sudo netstat -tlnp | grep :8090

# Or use ss
sudo ss -tlnp | grep :8090

Change the port using the -p flag during deployment.

Permission Errors

If you encounter permission errors:

# Ensure proper ownership of data directories
sudo chown -R spear:spear /var/lib/spear /var/log/spear

Encryption Key Validation

The encryption key must be exactly 16, 24, or 32 characters:

# Check key length
echo -n "$SPEAR_ENCRYPTION_KEY" | wc -c

If validation fails, generate a new key:

# Generate a 32-character key
export SPEAR_ENCRYPTION_KEY=$(openssl rand -base64 24)

Service Startup Failures

If the service fails to start:

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

# Verify binary permissions
ls -la /opt/spear/spear

# Check systemd service file
cat /etc/systemd/system/spear.service

Environment Variables

The systemd service file includes these environment variables:

Environment=SPEAR_ENCRYPTION_KEY=<your-key>
Environment=SPEAR_VERSION=<version>
Environment=SPEAR_PORT=<port>

For additional environment configuration, see Environment Variables.

Next Steps

• Configure Traefik SSL for HTTPS support
• Review Environment Variables for customization
• Set up automated backups via the Admin panel