paulmataruso/Palmr
1
0
Fork 0
mirror of https://github.com/kyantech/Palmr.git synced 2025-10-22 22:02:00 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
d6c9b0d7d263c671c164b604d06d221f91605460
Palmr/apps/docs/content/docs/3.2-beta/quick-start.mdx

410 lines
20 KiB
Plaintext
Raw Blame History

---
title: Quick Start (Docker)
icon: "Rocket"
---
import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
import { Card, CardGrid } from "@/components/ui/card";
Welcome to the fastest way to deploy <span className="font-bold">Palmr.</span> - 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](https://docs.docker.com/get-docker/))
- **Docker Compose** - Multi-container orchestration ([installation guide](https://docs.docker.com/compose/install/))
- **2GB+ available disk space** for the application and your files
- **Port 5487** available for the web interface
- **Port 3333** available for API access (optional)
<Callout>
**Platform Support**: Palmr. is developed on macOS and extensively tested on Linux servers. While we haven't formally
tested other platforms, Docker's cross-platform nature should ensure compatibility. Report any issues on our [GitHub
repository](https://github.com/kyantech/Palmr/issues).
</Callout>
## 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:
<Tabs items={['Named Volumes (Recommended)', 'Bind Mounts']}>
<Tab value="Named Volumes (Recommended)">
Docker-managed storage that provides the best balance of performance, security, and ease of use:
- **No Permission Issues**: Docker handles all permission management automatically
- **Performance**: Optimized for container workloads with better I/O performance
- **Production Ready**: Recommended for production deployments
### Configuration
Create a `docker-compose.yml` file:
```yaml
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)
# - NEXT_PUBLIC_UPLOAD_CHUNK_SIZE_MB=100 # Chunk size in MB for large file uploads (OPTIONAL - auto-calculates if not set)
volumes:
- palmr_data:/app/server
volumes:
palmr_data:
```
<Callout type="info">
**Having upload or permission issues?** Add `PALMR_UID=1000` and `PALMR_GID=1000` to your environment variables. Check our [UID/GID Configuration](/docs/3.2-beta/uid-gid-configuration) guide for more details.
</Callout>
### Deploy
```bash
docker-compose up -d
```
</Tab>
<Tab value="Bind Mounts">
Direct mapping to host filesystem directories, providing direct file access:
- **Direct Access**: Files are directly accessible from your host system
- **Development Friendly**: Easy to inspect, modify, or backup files manually
- **Platform Dependent**: May require UID/GID configuration, especially on NAS systems
### Configuration
Create a `docker-compose.yml` file:
```yaml
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=false # 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:
- ./data:/app/server
```
<Callout type="info">
**Having upload or permission issues?** Add `PALMR_UID=1000` and `PALMR_GID=1000` to your environment variables. Check our [UID/GID Configuration](/docs/3.2-beta/uid-gid-configuration) guide for more details.
</Callout>
### Deploy
```bash
docker-compose up -d
```
</Tab>
</Tabs>
## 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) |
| `CUSTOM_PATH` | - | Custom base path for disk space detection in manual installations with symlinks |
| `SECURE_SITE` | `false` | Enable secure cookies for HTTPS/reverse proxy deployments |
| `DEFAULT_LANGUAGE` | `en-US` | Default application language ([see available languages](/docs/3.2-beta/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](/docs/3.2-beta/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 |
| `NEXT_PUBLIC_UPLOAD_CHUNK_SIZE_MB` | auto-calculate | Chunk size in MB for large file uploads (see [Chunked Upload Configuration](/docs/3.2-beta/quick-start#chunked-upload-configuration)) |
| `DOWNLOAD_AUTO_SCALE` | `true` | Enable auto-scaling based on system memory |
<Callout type="info">
**Performance First**: Palmr runs without encryption by default for optimal speed and lower resource usage—perfect for
most use cases.
</Callout>
<Callout type="warn">
**Encryption Notice**: To enable encryption, set `DISABLE_FILESYSTEM_ENCRYPTION=false` and provide a 32+ character
`ENCRYPTION_KEY`. **Important**: This choice is permanent—switching encryption modes after uploading files will break
access to existing uploads.
</Callout>
<Callout>
**Using a Reverse Proxy?** Set `SECURE_SITE=true` and check our [Reverse Proxy
Configuration](/docs/3.2-beta/reverse-proxy-configuration) guide for proper HTTPS setup.
</Callout>
### Generate Encryption Keys (Optional)
Need file encryption? Generate a secure key:
<KeyGenerator />
> **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)
<Callout type="info">
**Learn More**: For complete API documentation, authentication, and integration examples, see our [API
Reference](/docs/3.2-beta/api) guide
</Callout>
<Callout type="warn">
**Production Ready?** Configure HTTPS with a valid SSL certificate for secure production deployments.
</Callout>
---
## Docker CLI Alternative
Prefer Docker commands over Compose? Here are the equivalent commands:
<Tabs items={["Named Volume", "Bind Mount"]}>
<Tab value="Named Volume">
```bash
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
```
<Callout type="info">
**Permission Issues?** Add `-e PALMR_UID=1000 -e PALMR_GID=1000` to the command above. See our [UID/GID Configuration](/docs/3.2-beta/uid-gid-configuration) guide for details.
</Callout>
</Tab>
<Tab value="Bind Mount">
```bash
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=true \ # 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 $(pwd)/data:/app/server \
--restart unless-stopped \
kyantech/palmr:latest
```
<Callout type="info">
**Permission Issues?** Add `-e PALMR_UID=1000 -e PALMR_GID=1000` to the command above. See our [UID/GID Configuration](/docs/3.2-beta/uid-gid-configuration) guide for details.
</Callout>
</Tab>
</Tabs>
---
## 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:
```yaml
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:
```yaml
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.
### Chunked Upload Configuration
Palmr supports configurable chunked uploading for large files. You can customize the chunk size by setting the following environment variable:
```yaml
environment:
- NEXT_PUBLIC_UPLOAD_CHUNK_SIZE_MB=100 # Chunk size in MB
```
**How it works:**
- If `NEXT_PUBLIC_UPLOAD_CHUNK_SIZE_MB` is set, Palmr will use this value (in megabytes) as the chunk size for all file uploads that exceed this threshold.
- If not set or left empty, Palmr automatically calculates optimal chunk sizes based on file size:
- Files ≤ 100MB: uploaded without chunking
- Files > 100MB and ≤ 1GB: 75MB chunks
- Files > 1GB: 150MB chunks
**When to configure:**
- **Default (not set):** Recommended for most use cases. Palmr will intelligently determine the best chunk size.
- **Custom value:** Set this if you have specific network conditions or want to optimize for your infrastructure (e.g., slower connections may benefit from smaller chunks like 50MB, while fast networks can handle larger chunks like 200MB, or the upload size per payload may be limited by a proxy like Cloudflare)
---
## Maintenance
### Updates
Keep Palmr up to date with the latest features and security patches:
```bash
docker-compose pull
docker-compose up -d
```
### Backup Your Data
**Named Volumes:**
```bash
docker run --rm -v palmr_data:/data -v $(pwd):/backup alpine tar czf /backup/palmr-backup.tar.gz -C /data .
```
**Bind Mounts:**
```bash
tar czf palmr-backup.tar.gz ./data
```
### Restore From Backup
**Named Volumes:**
```bash
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:**
```bash
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](/docs/3.2-beta/uid-gid-configuration)** - Configure user permissions for NAS systems and custom environments
- **[Download Memory Management](/docs/3.2-beta/download-memory-management)** - Configure large file download handling and queue system
- **[S3 Storage](/docs/3.2-beta/s3-configuration)** - Scale with Amazon S3 or compatible storage providers
- **[Manual Installation](/docs/3.2-beta/manual-installation)** - Manual installation and custom configurations
### Integration & Development
- **[API Reference](/docs/3.2-beta/api)** - Integrate Palmr. with your applications
<Callout type="info">
**Need help?** Check our [Troubleshooting Guide](/docs/3.2-beta/troubleshooting) for common issues and solutions.
</Callout>
---
**Questions?** Visit our [GitHub Issues](https://github.com/kyantech/Palmr/issues) or join the community discussions.
Reference in New Issue View Git Blame Copy Permalink