Getting Started

This guide will walk you through setting up Armor for the first time, from installation to using the comprehensive file management features.

Prerequisites
Quick Start
Core Features Overview
User Roles & Permissions
1. Regular Users (role: user)
2. Administrators (role: admin)
Advanced Configuration
Real-Time Features
1. Server-Sent Events (SSE)
2. Enhanced File Interface
Troubleshooting
1. Common Issues
2. Performance Optimization
Next Steps

Prerequisites

Before starting, ensure you have:

Node.js 22+ - Required for running Armor server
Database - SQLite3 (default), PostgreSQL, or MySQL for file metadata storage
Database Dependencies - pg package for PostgreSQL, mysql2 for MySQL (install via npm)
OpenSSL - For SSL certificate generation
Network Access - For HTTPS file serving

Quick Start

1. Installation

Option A: DEBIAN Package (Recommended)

# Download and install package
wget https://github.com/STARTcloud/armor/releases/latest/download/armor_*_amd64.deb
sudo gdebi -n armor_*.deb

# Start service
sudo systemctl enable --now armor

# Check status
sudo systemctl status armor

Option B: From Source

# Clone repository
git clone https://github.com/STARTcloud/armor.git
cd armor

# Install dependencies
npm ci

# Configure
cp dev.config.yaml config.yaml
# Edit config.yaml with your settings

# Start server
npm start

2. Initial Configuration

Edit the configuration file at /etc/armor/config.yaml (or config.yaml for source install):

# Server configuration
server:
  domain: localhost
  port: 443
  enable_api_docs: true
  show_root_index: false

# Authentication
authentication:
  jwt_secret: "your-jwt-secret-key-change-this"
  jwt_expiration: "24h"
  local:
    users:
      - username: admin
        password: admin123
        role: admin
        id: 1
      - username: user
        password: user123
        role: user
        id: 2

# SSL Configuration
ssl:
  key_file: "/etc/armor/ssl/key.pem"
  cert_file: "/etc/armor/ssl/cert.pem"
  generate_ssl: true

# File serving
served_directory: "/var/lib/armor/files"

3. First Access

Open your browser and navigate to https://your-server (or https://localhost for local)
Login: Use admin/admin123 (or your configured credentials)
Browse Files: Navigate through your file directories
Upload Files: Drag and drop files or use the upload button
Try API: Visit the API documentation for interactive Swagger UI

Core Features Overview

Authentication Methods

Navigate to your Armor server
Click “Login” button
Enter username/password from config

HTTP Basic Auth (CLI Tools)

# wget style (works with file downloads)
wget --no-check-certificate "https://admin:admin123@your-server/file.txt"

# curl style
curl -k -u admin:admin123 https://your-server/file.txt

API Key Authentication

# Generate API key via web interface (/api-keys)
curl -k -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-server/api/api-keys

File Operations

Upload Files

Web: Drag-and-drop to upload area
API: POST /{path} with multipart/form-data

Search Files

Web: Use search box (searches names and checksums)
API: POST /{path}/search with {"query":"searchterm"}

Create Folders

Web: Click folder+ button
API: POST /{path}/folders with {"folderName":"name"}

Rename Items

Web: Click pencil icon next to file/folder
API: PUT /{path}?action=rename with {"newName":"name"}

Swagger UI Features

Access comprehensive API documentation at /api-docs:

Dark theme: Professional appearance
API key integration: Fill auth from existing keys
Temporary keys: Generate testing keys on-demand
Dynamic server: Auto-detects your server URL
Interactive testing: Try all endpoints directly

User Roles & Permissions

Regular Users (role: user)

Download files: Full read access to all files
Create API keys: Download-only keys for automation
Browse directories: Navigate file structure

Administrators (role: admin)

Full file access: Upload, download, delete, rename
Folder management: Create and manage directories
API key management: Create keys with any permissions
System access: All file operations

Advanced Configuration

Rate Limiting

rate_limiting:
  window_minutes: 10
  max_requests: 100
  message: "Too many requests, please try again later."

OIDC Authentication (Google, etc.)

authentication:
  oidc_providers:
    google:
      enabled: true
      client_id: "your-google-client-id"
      client_secret: "your-google-client-secret"
      display_name: "Sign in with Google"

Swagger UI Customization

swagger:
  allow_full_key_retrieval: true
  allow_temp_key_generation: true
  temp_key_expiration_hours: 1

Real-Time Features

Server-Sent Events (SSE)

Armor provides real-time updates:

File uploads: See new files appear instantly
Checksum updates: Watch checksums calculate in real-time
File operations: Renames, deletes sync across all users
Multi-user collaboration: All connected users see changes

Enhanced File Interface

Click file icons: Copy links to clipboard
Long-press file icons: Force download (bypasses browser preview)
Rename functionality: In-place editing with real-time updates
Animated feedback: Visual confirmations for all actions

Troubleshooting

Common Issues

Service Won’t Start

# Check logs
sudo journalctl -u armor -f

# Verify config
sudo armor --check-config

# Check permissions
sudo chown -R armor:armor /var/lib/armor

Cannot Upload Files

Verify you’re logged in as admin user
Check directory permissions: sudo chown armor:armor /var/lib/armor/files
Ensure disk space available

SSL Certificate Issues

# Regenerate certificates
sudo rm -rf /etc/armor/ssl/*
sudo systemctl restart armor

API Key Problems

Only admin users can create upload/delete API keys
Regular users can only create download-only keys
Check permissions in Swagger UI

Performance Optimization

For large file collections:

Enable file watching: Real-time checksum calculation
Database optimization: Regular SQLite maintenance
Rate limiting: Adjust based on usage patterns

Next Steps

Once Armor is running:

Explore the API - Interactive Swagger documentation
Configure Authentication - Set up OIDC or additional users
Installation Guide - Production deployment best practices

Need help? Check our Support Documentation or open an issue.