Administrators
Users
API Reference

Installation

This guide will walk you through the installation process of sftproo. Self-Hosted installation is not yet available to the public, the documentation below will be more applicable when this happens.

Prerequisites

  • Docker and Docker Compose installed on your server
  • A server with at least 2GB RAM and 10GB storage
  • Ports 2222 (SFTP) and 8443 (Web UI) available
  • A valid domain name (optional, but recommended for SSL)

Quick Start with Docker Compose

1. Create a directory for sftproo:

mkdir /opt/sftproo
cd /opt/sftproo

2. Create a docker-compose.yml file:

version: '3.8'

services:
  sftproo:
    image: sftproo/sftproo:latest
    container_name: sftproo
    ports:
      - "2222:2222"  # SFTP port
      - "8443:8443"  # Web UI port
    volumes:
      - ./data:/data
      - ./config:/config
      - ./backups:/backups
    environment:
      - SFTPROO_DB_HOST=mariadb
      - SFTPROO_DB_NAME=sftproo
      - SFTPROO_DB_USER=sftproo
      - SFTPROO_DB_PASSWORD=changeme
      - SFTPROO_SESSION_SECRET=changemetosomethingrandom
    depends_on:
      - mariadb
    restart: unless-stopped

  mariadb:
    image: mariadb:10.11
    container_name: sftproo-db
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=sftproo
      - MYSQL_USER=sftproo
      - MYSQL_PASSWORD=changeme
    volumes:
      - ./database:/var/lib/mysql
    restart: unless-stopped

3. Start the services:

docker-compose up -d

4. Access the web interface at https://your-server:8443

Important: Change all default passwords and the session secret before deploying to production!

AWS Marketplace Deployment

sftproo is available as a pre-configured AMI in the AWS Marketplace:

  1. Search for "sftproo" in the AWS Marketplace (or click here to get started)
  2. Select your instance type (t3.small or larger recommended)
  3. Configure security groups to allow ports 22, 2222, and 8443
  4. Launch the instance, and when ready connect to it using SSH to retreive your access credentials
    ssh -i YOUR_SSH_KEY ubuntu@instance.ip.address
  5. Open file /opt/default-sftproo-credentails.txt to access Unique Admin Password
    (username: admin, password: unique-password)
  6. Go to the web browser and use the password above to setup your new sftp server
    https://ip.add.re.ss:8443

Azure Marketplace Deployment

Deploy sftproo from the Azure Marketplace:

  1. Search for "sftproo" in the Azure Marketplace(or click here to get started)
  2. Choose your VM size (B2s or larger recommended)
  3. Configure network security rules for ports 22, 2222, and 8443
  4. Launch the instance, and when ready connect to it using SSH to retreive your access credentials
    ssh -i YOUR_SSH_KEY azureuser@instance.ip.address
  5. Open file /opt/default-sftproo-credentails.txt to access Unique Admin Password
    (username: admin, password: unique-password)
  6. Go to the web browser and use the password above to setup your new sftp server
    https://ip.add.re.ss:8443

Configuration

Initial Setup

After installation, access the web interface and log in with the credentials obtained above:

  • Username: admin
  • Password: As obtained above
Change the admin password immediately after first login!

Environment Variables

sftproo can be configured using environment variables:

Variable Description Default
SFTPROO_DB_HOST Database host localhost
SFTPROO_DB_PORT Database port 3306
SFTPROO_DB_NAME Database name sftproo
SFTPROO_DB_USER Database user sftproo
SFTPROO_DB_PASSWORD Database password -
SFTPROO_STORAGE_PATH Path for user file storage /data
SFTPROO_BACKUP_PATH Path for backups /backups
SFTPROO_SESSION_SECRET Session encryption key -
SFTPROO_SFTP_PORT SFTP server port 2222
SFTPROO_HTTP_PORT Web interface port 8443

SSL/TLS Configuration

sftproo uses self-signed certificates by default. For production, you should use proper SSL certificates:

Option 1: Let's Encrypt

# Using Traefik (included in docker-compose)
services:
  traefik:
    image: traefik:v2.10
    command:
      - "--certificatesresolvers.letsencrypt.acme.email=your@email.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
    labels:
      - "traefik.http.routers.sftproo.tls.certresolver=letsencrypt"

Option 2: Custom Certificates (Recommended)

# Mount your certificates
volumes:
  - ./certs/server.crt:/config/sftproo-server.crt
  - ./certs/server.key:/config/sftproo-server.pem

Storage Configuration

By default, sftproo stores files locally. For cloud storage, configure S3:(Feature in development)

SFTPROO_STORAGE_TYPE=s3
SFTPROO_S3_BUCKET=your-bucket-name
SFTPROO_S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

User Management

Creating Users

To create a new user via the web interface:

  1. Navigate to Users in the admin panel
  2. Click Add User
  3. Fill in the required fields:
    • Username: Unique identifier (alphanumeric, no spaces)
    • Email: User's email address
    • Password: Strong password (min 8 characters)
  4. Select user role:
    • Admin: Full system access
    • User: SFTP access only
  5. Click Create User

SSH Key Management

Users can authenticate using SSH keys for enhanced security:

Adding SSH Keys:

  1. Edit the user in the admin panel
  2. Click Manage SSH Keys
  3. Either:
    • Paste an existing public key
    • Generate a new key pair (download the private key immediately!)
  4. Save the changes

User Quotas and Limits

Set storage quotas and connection limits per user:

  • Storage Quota: Maximum storage space (in GB)
  • Max Connections: Concurrent SFTP connections allowed
  • Bandwidth Limit: Upload/download speed restrictions

Backup & Restore

Automated Backups

Configure automatic backups in the Settings panel:

  1. Navigate to Settings → Backup
  2. Enable Automated Backups
  3. Set backup schedule (daily, weekly, monthly)
  4. Configure retention policy (number of backups to keep)
  5. Choose backup destination (local or S3)

Manual Backup

Create an immediate backup:

# Via CLI
docker exec sftproo sftproo-backup create

# Via Web UI
Settings → Backup → Create Backup Now

Backup Contents

Each backup includes:

  • Database (users, settings, permissions)
  • Configuration files
  • SSH host keys
  • User files (optional, can be large)

Restore Process

To restore from a backup:

  1. Stop the sftproo service
  2. Run the restore command: 
    docker exec sftproo sftproo-backup restore backup-2025-01-15.tar.gz
  3. Restart the service
  4. Verify the restoration was successful
Tip: Test your restore process regularly to ensure backups are working correctly.

Backup Encryption

Backups can be encrypted at the point of capture. To decrypt a backup manually:

# Use the decrypt_backup utility
./decrypt_backup -input backup-2025-01-15.tar.gz.enc -output backup.tar.gz

Security Settings

Access Control Lists (ACL)

Restrict access based on IP addresses:

  1. Navigate to Settings → Security → ACL
  2. Add allowed IP addresses or CIDR ranges
  3. Enable Whitelist Mode to block all other IPs

Security Best Practices

  • Use strong, unique passwords for all accounts
  • Enable SSH key authentication and disable password auth
  • Regularly update sftproo to the latest version
  • Monitor logs for suspicious activity
  • Use IP whitelisting for sensitive deployments
  • Enable audit logging for compliance

Audit Logging

sftproo logs all important activities:

  • User logins/logouts
  • File uploads/downloads/deletions
  • Configuration changes
  • Failed authentication attempts

Access logs via Settings → Logs or:

docker logs sftproo

Users Guide: Getting Started

Welcome to sftproo! This guide will help you connect to the SFTP server and start transferring files.

Your Credentials

Your administrator should provide you with:

  • Server Address: The hostname or IP of the SFTP server
  • Port: Usually 2222 (not the standard SSH port 22)
  • Username: Your unique username
  • Password: Your initial password (change it on first login)
  • SSH Key: (Optional) A private key file for authentication

First Connection

Using the command line:

sftp -P 2222 username@server.example.com

You'll be prompted to accept the server's host key on first connection. Type "yes" to continue.

Changing Your Password

To change your password via the web interface:

  1. Log in to https://server.example.com:8443
  2. Click your username in the top right
  3. Select Change Password
  4. Enter your current and new passwords
  5. Click Update Password

File Management

Basic SFTP Commands

Once connected, use these commands to manage files:

Command Description Example
ls List files in current directory ls -la
cd Change directory cd documents
pwd Show current directory pwd
mkdir Create directory mkdir newfolder
put Upload file put localfile.txt
get Download file get remotefile.txt
rm Delete file rm oldfile.txt
rmdir Delete empty directory rmdir oldfolder
rename Rename file or directory rename old.txt new.txt

Batch Transfers

Transfer multiple files at once:

# Upload all .pdf files
put *.pdf

# Download all files in a directory
get -r documents/

# Upload entire directory
put -r local_folder/

Resume Interrupted Transfers

If a transfer is interrupted, resume it:

# Resume upload
reput largefile.zip

# Resume download
reget largefile.zip

SSH Key Management

Generating SSH Keys

Create a new SSH key pair on your local machine:

On Linux/Mac:

ssh-keygen -t ed25519 -f ~/.ssh/sftproo_key -C "your_email@example.com"

On Windows (PowerShell):

ssh-keygen -t ed25519 -f $HOME\.ssh\sftproo_key -C "your_email@example.com"

Adding Your Public Key

Option 1: Via Web Interface

  1. Log in to the web interface
  2. Go to Profile → SSH Keys
  3. Click Add SSH Key
  4. Paste your public key (contents of sftproo_key.pub)
  5. Give it a descriptive name
  6. Click Save

Option 2: Ask your administrator to add it for you

Using SSH Keys for Authentication

Connect using your private key:

sftp -P 2222 -i ~/.ssh/sftproo_key username@server.example.com

SSH Agent

For convenience, add your key to the SSH agent:

# Start SSH agent
eval $(ssh-agent)

# Add your key
ssh-add ~/.ssh/sftproo_key

# Now connect without specifying the key
sftp -P 2222 username@server.example.com

SFTP Clients

While command-line SFTP is powerful, graphical clients can be more user-friendly.

Recommended Clients

Windows

  • WinSCP (Free)
    1. Download from winscp.net
    2. Select "SFTP" as protocol
    3. Enter server, port 2222, username, and password
    4. For SSH keys, go to Advanced → SSH → Authentication
  • FileZilla (Free)
    1. Download from filezilla-project.org
    2. Use sftp://server.example.com as host
    3. Set port to 2222
    4. Enter credentials and connect

macOS

  • Cyberduck (Free)
    1. Download from cyberduck.io
    2. Choose "SFTP (SSH File Transfer Protocol)"
    3. Enter server details with port 2222
    4. Add SSH key in connection settings if needed
  • Transmit (Paid)
    1. Premium option with advanced features
    2. Excellent integration with macOS
    3. Supports sync and automatic uploads

Linux

  • FileZilla - Available in most package managers
  • Nautilus/Dolphin - Built-in file managers support SFTP
    • Use address: sftp://username@server:2222

Mobile Clients

  • iOS: FTPManager, Secure ShellFish
  • Android: Total Commander, AndFTP

Troubleshooting

Common Connection Issues

Connection Refused

If you get "Connection refused" errors:

  • Verify the server address and port (should be 2222, not 22)
  • Check if you're behind a firewall that blocks port 2222
  • Ensure the SFTP service is running (contact your admin)

Authentication Failed

If authentication fails:

  • Double-check your username (case-sensitive)
  • Verify your password or SSH key
  • Ensure your account hasn't been locked
  • Check if your IP is whitelisted (if ACL is enabled)

Permission Denied

If you can't access certain directories:

  • You're restricted to your home directory
  • Check file permissions with ls -la
  • Contact admin if you need additional access

File Transfer Issues

Slow Transfers

  • Check your internet connection speed
  • Try transferring smaller files first
  • Use compression for text files: put -z file.txt
  • Consider using multiple concurrent connections

Incomplete Transfers

  • Use resume capabilities: reput or reget
  • Check available storage space
  • Verify you haven't exceeded your quota

Getting Help

If you continue to experience issues:

  1. Check the FAQ section
  2. Contact your system administrator
  3. Provide error messages and steps to reproduce