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

1. Navigate to Admin > System > Backups
2. Click Create Backup
3. Select backup type
4. Optionally add a description
5. Click Start Backup
6. 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	admin@company.com

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

Caution

Restoring a backup replaces all current data. Create a backup before restoring.

1. Navigate to Admin > System > Backups
2. Select the backup to restore
3. Click Restore
4. Confirm the operation
5. Wait for restoration to complete
6. 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:

1. Navigate to Admin > System > Database
2. Click Optimize Database
3. System runs VACUUM and ANALYZE
4. Review optimization results

Run optimization:

• After large deletions
• Monthly for regular maintenance
• When performance degrades

Data Export

Export data for migration or analysis:

1. Select collections to export
2. Choose format (JSON, CSV)
3. Click Export
4. 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:

1. View error details
2. Retry the job
3. 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

1. Navigate to Admin > System > Logs
2. Select log type
3. Filter by date, level, or search
4. 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:

1. Navigate to Admin > System > Maintenance
2. Set maintenance message
3. Set expected duration (optional)
4. Click Enable Maintenance Mode

Maintenance Tasks

With maintenance mode enabled:

• Database migrations
• Large data imports
• System upgrades
• Performance optimization

Disabling Maintenance Mode

1. Complete maintenance tasks
2. Navigate to Admin > System > Maintenance
3. Click Disable Maintenance Mode
4. Verify system is operational

---

Updates

Version Information

View current version:

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

Update Process

1. Download new release
2. Enable maintenance mode
3. Create backup
4. Stop current instance
5. Replace binary
6. Start new instance
7. Verify migrations ran
8. Disable maintenance mode
9. Verify functionality

Automatic Updates

Note

Automatic updates are not currently supported. Updates must be applied manually.

---

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:

1. Navigate to Admin > System > Resources
2. Review current utilization
3. Adjust limits as needed

---

Troubleshooting

System Won’t Start

1. Check logs for errors
2. Verify disk space available
3. Check port availability
4. Verify encryption key set
5. Check file permissions

Slow Performance

1. Review database size
2. Run database optimization
3. Check disk space
4. Review background job queue
5. Consider resource limits

Backup Failures

1. Check disk space
2. Verify S3 credentials (if applicable)
3. Review backup job logs
4. Test manual backup
5. Check file permissions

High Memory Usage

1. Review active connections
2. Check for large file uploads
3. Review background job queue
4. Consider memory limits
5. Restart if necessary