Quick Start (Docker)

Welcome to the fastest way to deploy Palmr. - your secure, self-hosted file sharing solution. This guide will have you up and running in minutes, whether you're new to self-hosting or an experienced developer.

Palmr. offers flexible deployment options to match your infrastructure needs. This guide focuses on Docker deployment with our recommended filesystem storage, perfect for most use cases.

Prerequisites

Before you begin, make sure you have:

• Docker - Container runtime (installation guide)
• Docker Compose - Multi-container orchestration (installation guide)
• 2GB+ available disk space for the application and your files
• Port 5487 available for the web interface
• Port 3333 available for API access (optional)

Storage Options

Palmr. supports two storage approaches for persistent data:

• Named Volumes (Recommended) - Docker-managed storage with optimal performance and no permission issues
• Bind Mounts - Direct host filesystem access, ideal for development and direct file management

Deployment Options

Choose your storage method based on your needs:

services:
  palmr:
    image: kyantech/palmr:latest
    container_name: palmr
    restart: unless-stopped
    ports:
      - "5487:5487" # Web interface
      # - "3333:3333" # API (optional)
    environment:
      # Optional: Uncomment and configure as needed (if you don`t use, you can remove)
      # - ENABLE_S3=true # Set to true to enable S3-compatible storage
      # - DISABLE_FILESYSTEM_ENCRYPTION=true # Set to false to enable file encryption
      # - ENCRYPTION_KEY=your-secure-key-min-32-chars # Required only if encryption is enabled
      # - PALMR_UID=1000 # UID for the container processes (default is 1000)
      # - PALMR_GID=1000 # GID for the container processes (default is 1000)
      # - SECURE_SITE=false # Set to true if you are using a reverse proxy
      # - DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
      # - PRESIGNED_URL_EXPIRATION=3600 # Duration in seconds for presigned URL expiration (optional, defaults to 3600 seconds / 1 hour)
      # - DOWNLOAD_MAX_CONCURRENT=5 # Maximum simultaneous downloads (auto-scales if not set)
      # - DOWNLOAD_MEMORY_THRESHOLD_MB=2048 # Memory threshold in MB before throttling (auto-scales if not set)
      # - DOWNLOAD_QUEUE_SIZE=25 # Maximum queue size for pending downloads (auto-scales if not set)
      # - DOWNLOAD_MIN_FILE_SIZE_GB=3.0 # Minimum file size in GB to activate memory management (default: 3.0)
      # - DOWNLOAD_AUTO_SCALE=true # Enable auto-scaling based on system memory (default: true)
      # - NODE_OPTIONS=--expose-gc # Enable garbage collection for large downloads (recommended for production)
    volumes:
      - palmr_data:/app/server
 
volumes:
  palmr_data:

docker-compose up -d

Configuration

Customize Palmr's behavior with these environment variables:

| Variable | Default | Description | | ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- | --- | | ENABLE_S3 | false | Enable S3-compatible storage backends | | S3_ENDPOINT | - | S3 server endpoint URL (required when using S3) | | S3_PORT | - | S3 server port (optional when using S3) | | S3_USE_SSL | - | Enable SSL for S3 connections (optional when using S3) | | S3_ACCESS_KEY | - | S3 access key for authentication (required when using S3) | | S3_SECRET_KEY | - | S3 secret key for authentication (required when using S3) | | S3_REGION | - | S3 region configuration (optional when using S3) | | S3_BUCKET_NAME | - | S3 bucket name for file storage (required when using S3) | | S3_FORCE_PATH_STYLE | false | Force path-style S3 URLs (optional when using S3) | | S3_REJECT_UNAUTHORIZED | true | Enable strict SSL certificate validation for S3 (set to false for self-signed certificates) | | ENCRYPTION_KEY | - | Required when encryption is enabled: 32+ character key for file encryption | | DISABLE_FILESYSTEM_ENCRYPTION | true | Disable file encryption for better performance (set to false to enable encryption) | | PRESIGNED_URL_EXPIRATION | 3600 | Duration in seconds for presigned URL expiration (applies to both filesystem and S3 storage) | | SECURE_SITE | false | Enable secure cookies for HTTPS/reverse proxy deployments | | DEFAULT_LANGUAGE | en-US | Default application language (see available languages) | | | PALMR_UID | 1000 | User ID for container processes (helps with file permissions) | | PALMR_GID | 1000 | Group ID for container processes (helps with file permissions) | | NODE_OPTIONS | - | Node.js options (recommended: --expose-gc for garbage collection in production) | | DOWNLOAD_MAX_CONCURRENT | auto-scale | Maximum number of simultaneous downloads (see Download Memory Management) | | DOWNLOAD_MEMORY_THRESHOLD_MB | auto-scale | Memory threshold in MB before throttling | | DOWNLOAD_QUEUE_SIZE | auto-scale | Maximum queue size for pending downloads | | DOWNLOAD_MIN_FILE_SIZE_GB | 3.0 | Minimum file size in GB to activate memory management | | DOWNLOAD_AUTO_SCALE | true | Enable auto-scaling based on system memory |

Generate Encryption Keys (Optional)

Need file encryption? Generate a secure key:

Pro Tip: Only enable encryption if you're handling sensitive data. For most users, the default unencrypted mode provides better performance.

Access Your Instance

Once deployed, open Palmr in your browser:

• Web Interface: http://localhost:5487 (local) or http://YOUR_SERVER_IP:5487 (remote)
• API Documentation: http://localhost:3333/docs (if port 3333 is exposed)

Docker CLI Alternative

Prefer Docker commands over Compose? Here are the equivalent commands:

docker run -d \
  --name palmr \
  # Optional: Uncomment and configure as needed (if you don`t use, you can remove)
  # -e ENABLE_S3=true \ # Set to true to enable S3-compatible storage (OPTIONAL - default is false)
  # -e DISABLE_FILESYSTEM_ENCRYPTION=false \ # Set to false to enable file encryption (ENCRYPTION_KEY becomes required) | (OPTIONAL - default is true)
  # -e ENCRYPTION_KEY=your-secure-key-min-32-chars # Required only if encryption is enabled
  # -e PALMR_UID=1000 # UID for the container processes (default is 1000)
  # -e PALMR_GID=1000 # GID for the container processes (default is 1000)
  # -e SECURE_SITE=false # Set to true if you are using a reverse proxy
  # -e DEFAULT_LANGUAGE=en-US # Default language for the application (optional, defaults to en-US)
  -p 5487:5487 \
  -p 3333:3333 \
  -v palmr_data:/app/server \
  --restart unless-stopped \
  kyantech/palmr:latest

Common Configuration Options

Presigned URL Expiration

Palmr. uses temporary URLs (presigned URLs) for secure file access. These URLs expire after a configurable time period to enhance security.

Default: 1 hour (3600 seconds)

You can customize this for all storage types (filesystem or S3) by adding:

environment:
  - PRESIGNED_URL_EXPIRATION=7200 # 2 hours

When to adjust:

• Shorter time (1800 = 30 min): Higher security, but users may need to refresh download links
• Longer time (7200-21600 = 2-6 hours): Better for large file transfers, but URLs stay valid longer
• Default (3600 = 1 hour): Good balance for most use cases

File Encryption

For filesystem storage, you can enable file encryption:

environment:
  - DISABLE_FILESYSTEM_ENCRYPTION=false
  - ENCRYPTION_KEY=your-secure-32-character-key-here

Note: S3 storage handles encryption through your S3 provider's encryption features.

Maintenance

Updates

Keep Palmr up to date with the latest features and security patches:

docker-compose pull
docker-compose up -d

Backup Your Data

Named Volumes:

docker run --rm -v palmr_data:/data -v $(pwd):/backup alpine tar czf /backup/palmr-backup.tar.gz -C /data .

Bind Mounts:

tar czf palmr-backup.tar.gz ./data

Restore From Backup

Named Volumes:

docker-compose down
docker run --rm -v palmr_data:/data -v $(pwd):/backup alpine tar xzf /backup/palmr-backup.tar.gz -C /data
docker-compose up -d

Bind Mounts:

docker-compose down
tar xzf palmr-backup.tar.gz
docker-compose up -d

What's Next?

Your Palmr instance is ready! Here's what you can explore:

Advanced Configuration

• UID/GID Configuration - Configure user permissions for NAS systems and custom environments
• Download Memory Management - Configure large file download handling and queue system
• S3 Storage - Scale with Amazon S3 or compatible storage providers
• Manual Installation - Manual installation and custom configurations

Integration & Development

• API Reference - Integrate Palmr. with your applications

Questions? Visit our GitHub Issues or join the community discussions.