System

Manage system-level operations including backups, maintenance tasks, and health monitoring.

System Overview

🖥️ System Administration Dashboard Screenshot

Access the system dashboard at Admin > System to view:

System health status
Resource utilization
Active background jobs
Recent system events

Backup Management

🖥️ Backup Management Interface Screenshot

Backup Types

Type	Contents	Use Case
Full	Database + files	Disaster recovery
Database Only	Database without uploads	Quick snapshots
Incremental	Changes since last backup	Efficient storage

Manual Backup

Navigate to Admin > System > Backups
Click Create Backup
Select backup type
Optionally add a description
Click Start Backup
Download when complete

Automated Backups

Configure scheduled backups:

Setting	Description	Example
Schedule	Cron expression or preset	Daily at 2:00 AM
Retention	Number of backups to keep	30
Destination	Local or S3 storage	S3 bucket
Notification	Email on completion/failure	[email protected]

Schedule Presets:

Hourly
Daily (2:00 AM)
Weekly (Sunday 2:00 AM)
Custom cron expression

Backup Destinations

Local Storage:

Stored in ./pb_data/backups/
Accessible for download via admin panel
Limited by local disk space

S3-Compatible Storage:

Requires S3 configuration in Services
Automatic upload after backup
Better for disaster recovery

Restoring from Backup

Navigate to Admin > System > Backups
Select the backup to restore
Click Restore
Confirm the operation
Wait for restoration to complete
System will restart automatically

Backup Best Practices

Schedule daily backups minimum
Keep at least 7 days of backups
Store backups off-site (S3)
Test restoration periodically
Document backup procedures

Database Management

🖥️ Database Management Interface Screenshot

Database Information

View database statistics:

Metric	Description
Size	Total database file size
Tables	Number of collections
Records	Total record count
Connections	Active database connections

Database Optimization

Optimize database performance:

Navigate to Admin > System > Database
Click Optimize Database
System runs VACUUM and ANALYZE
Review optimization results

Run optimization:

After large deletions
Monthly for regular maintenance
When performance degrades

Data Export

Export data for migration or analysis:

Select collections to export
Choose format (JSON, CSV)
Click Export
Download the export file

Background Jobs

🖥️ Background Jobs Queue Screenshot

Job Types

Job	Purpose	Frequency
Backup	Automated backups	Scheduled
Cleanup	Temp file removal	Daily
Export	Async PDF generation	On-demand
Sync	Real-time collaboration sync	Continuous

Job Queue

View and manage background jobs:

Status	Description
Pending	Waiting to run
Running	Currently executing
Completed	Finished successfully
Failed	Finished with error

Failed Job Management

For failed jobs:

View error details
Retry the job
Or cancel and investigate

System Health

Health Checks

Monitor system components:

Component	Checks
Database	Connection, query performance
Storage	Disk space, file access
Memory	Usage, available
CPU	Utilization
Network	Connectivity

Health Endpoint

Programmatic health check:

curl https://your-spear-instance/api/health

Response:

{
  "status": "healthy",
  "components": {
    "database": "healthy",
    "storage": "healthy",
    "memory": "healthy"
  },
  "version": "1.0.0",
  "uptime": "5d 12h 30m"
}

Monitoring Integration

Export metrics for external monitoring:

curl https://your-spear-instance/api/metrics

Compatible with Prometheus, Grafana, etc.

Logs

🖥️ Log Viewer Interface Screenshot

Log Types

Log	Contents
Application	General application events
Access	HTTP request logs
Error	Error and exception details
Audit	Security-relevant events

Viewing Logs

Navigate to Admin > System > Logs
Select log type
Filter by date, level, or search
Export if needed

Log Retention

Configure log retention:

Setting	Default	Description
Application Logs	30 days	General logs
Access Logs	7 days	Request logs
Error Logs	90 days	Error details
Audit Logs	1 year	Security events

External Logging

Forward logs to external services:

# Environment variable configuration
LOG_OUTPUT=stdout
LOG_FORMAT=json
LOG_LEVEL=info

Compatible with:

ELK Stack (Elasticsearch, Logstash, Kibana)
Splunk
CloudWatch
Datadog

Maintenance Mode

Enabling Maintenance Mode

During maintenance, users see a maintenance page:

Navigate to Admin > System > Maintenance
Set maintenance message
Set expected duration (optional)
Click Enable Maintenance Mode

Maintenance Tasks

With maintenance mode enabled:

Database migrations
Large data imports
System upgrades
Performance optimization

Disabling Maintenance Mode

Complete maintenance tasks
Navigate to Admin > System > Maintenance
Click Disable Maintenance Mode
Verify system is operational

Updates

Version Information

View current version:

Navigate to Admin > System > About
Or run ./spear --version

Update Process

Download new release
Enable maintenance mode
Create backup
Stop current instance
Replace binary
Start new instance
Verify migrations ran
Disable maintenance mode
Verify functionality

Automatic Updates

Resource Limits

Configuration

Set resource limits via environment variables:

# Memory limit
SPEAR_MAX_MEMORY=2GB

# File upload limit
SPEAR_MAX_UPLOAD_SIZE=50MB

# Concurrent requests
SPEAR_MAX_CONNECTIONS=100

# Background job workers
SPEAR_JOB_WORKERS=4

Monitoring Limits

View resource usage vs limits:

Navigate to Admin > System > Resources
Review current utilization
Adjust limits as needed

Troubleshooting

System Won’t Start

Check logs for errors
Verify disk space available
Check port availability
Verify encryption key set
Check file permissions

Slow Performance

Review database size
Run database optimization
Check disk space
Review background job queue
Consider resource limits

Backup Failures

Check disk space
Verify S3 credentials (if applicable)
Review backup job logs
Test manual backup
Check file permissions

High Memory Usage

Review active connections
Check for large file uploads
Review background job queue
Consider memory limits
Restart if necessary