Services

Configure external services that SPEAR relies on for email delivery, file storage, and other functionality.

Available Services

Service	Purpose	Required
SMTP	Email delivery	Optional
S3 Storage	Backup storage	Optional
File Storage	Local file settings	Configured

SMTP Configuration

SMTP enables email functionality for password resets, notifications, and report sharing.

🖥️ SMTP Configuration Settings Screenshot

Settings

Navigate to Admin > Services > SMTP

Setting	Description	Example
Host	SMTP server hostname	`smtp.gmail.com`
Port	SMTP port	`587`
Username	Authentication username	`[email protected]`
Password	Authentication password	`app-password`
Sender Name	Display name for emails	`SPEAR Notifications`
Sender Email	From address	`[email protected]`
Encryption	TLS/STARTTLS/None	`STARTTLS`

Common Provider Settings

Gmail / Google Workspace:

Host: smtp.gmail.com
Port: 587
Encryption: STARTTLS
Username: [email protected]
Password: App Password (not regular password)

Microsoft 365:

Host: smtp.office365.com
Port: 587
Encryption: STARTTLS
Username: [email protected]
Password: App Password or OAuth token

Amazon SES:

Host: email-smtp.us-east-1.amazonaws.com
Port: 587
Encryption: STARTTLS
Username: SMTP credentials from SES console
Password: SMTP credentials from SES console

SendGrid:

Host: smtp.sendgrid.net
Port: 587
Encryption: STARTTLS
Username: apikey
Password: Your SendGrid API key

Testing SMTP

Configure all settings
Click Test Connection
Enter a test email address
Click Send Test
Verify email received

Troubleshooting SMTP

Connection timeout:

Verify hostname and port
Check firewall rules
Try alternate ports (465, 25)

Authentication failed:

Verify username and password
For Gmail, use App Password
Check if account allows SMTP access

SSL/TLS errors:

Try different encryption options
Verify certificate is valid
Check for proxy interference

S3-Compatible Storage

Configure external storage for backups and large file storage.

🖥️ S3 Storage Configuration Screenshot

Settings

Navigate to Admin > Services > Storage

Setting	Description
Provider	S3, MinIO, Backblaze B2, etc.
Endpoint	S3-compatible endpoint URL
Region	Storage region
Bucket	Bucket name
Access Key	Access key ID
Secret Key	Secret access key
Path Prefix	Optional folder prefix

Provider Examples

AWS S3:

Endpoint: https://s3.amazonaws.com
Region: us-east-1
Bucket: your-bucket-name
Access Key: AKIAIOSFODNN7EXAMPLE
Secret Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

MinIO (Self-hosted):

Endpoint: https://minio.yourserver.com
Region: us-east-1
Bucket: spear-backups
Access Key: minioadmin
Secret Key: minioadmin

Backblaze B2:

Endpoint: https://s3.us-west-002.backblazeb2.com
Region: us-west-002
Bucket: your-bucket-name
Access Key: keyID from B2
Secret Key: applicationKey from B2

DigitalOcean Spaces:

Endpoint: https://nyc3.digitaloceanspaces.com
Region: nyc3
Bucket: your-space-name
Access Key: Spaces access key
Secret Key: Spaces secret key

Cloudflare R2:

Endpoint: https://your-account-id.r2.cloudflarestorage.com
Region: auto
Bucket: your-bucket-name
Access Key: R2 access key
Secret Key: R2 secret key

Testing Storage Connection

Configure all settings
Click Test Connection
System uploads a small test file
Verify test succeeds
Save configuration

Storage Usage

S3 storage is used for:

Automated backups (if configured)
Large file offloading (optional)
Backup export destination

File Storage Settings

Configure local file storage behavior.

Settings

Navigate to Admin > Services > Files

Setting	Description	Default
Max Upload Size	Maximum file upload size	50MB
Allowed Types	Permitted file extensions	images, documents
Storage Path	Local storage directory	`./pb_data/storage`

File Type Restrictions

Configure allowed file types by category:

Category	Extensions
Images	.jpg, .jpeg, .png, .gif, .svg, .webp
Documents	.pdf, .doc, .docx, .xls, .xlsx
Archives	.zip, .tar, .gz
Data	.json, .xml, .csv

Storage Cleanup

Configure automatic cleanup of temporary files:

Setting	Description
PDF Export Retention	Days to keep exported PDFs
Upload Temp Retention	Days to keep temporary uploads
Orphaned File Cleanup	Remove unreferenced files

Service Health Monitoring

🖥️ Service Health Status Dashboard Screenshot

Status Dashboard

View service health at Admin > Services > Status

Service	Indicators
SMTP	Last successful send, error rate
S3 Storage	Connection status, last backup
Database	Size, connection count
Background Jobs	Queue length, processing rate

Alerts

Configure alerts for service issues:

Navigate to Admin > Services > Alerts
Enable alerts for critical services
Set notification threshold
Configure notification method (email if SMTP configured)

Environment Variables

Services can also be configured via environment variables:

SMTP

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=password
SMTP_SENDER_NAME="SPEAR"
SMTP_SENDER_EMAIL=[email protected]

S3 Storage

S3_ENDPOINT=https://s3.amazonaws.com
S3_REGION=us-east-1
S3_BUCKET=your-bucket
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key

Environment variables override database configuration.

Best Practices

SMTP

Use dedicated email service (SendGrid, SES) for production
Create application-specific passwords
Set up SPF/DKIM/DMARC for deliverability
Monitor bounce and complaint rates

S3 Storage

Use separate bucket for SPEAR
Enable versioning for backup protection
Set up lifecycle policies for cost management
Use IAM with minimal required permissions

Security

Never commit credentials to version control
Use environment variables for sensitive settings
Rotate access keys regularly
Audit service access logs