How to Self-Host Gokapi with Docker Compose

What Is Gokapi?

Gokapi is a lightweight, self-hosted file sharing server written in Go. Upload files via the admin interface or API, share download links with configurable expiry (time-based and download-count-based), and optionally store files in S3-compatible storage. Gokapi v2 added multi-user support with granular permissions, file requests (external users can upload files to you), and a CLI tool for scripted uploads.

Gokapi fills the gap between PicoShare (minimal, no encryption) and Send (encrypted, needs Redis). It adds S3 support, end-to-end encryption (optional), multi-user management, and a clean admin dashboard without requiring external dependencies beyond a single container.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
256 MB of free RAM (minimum)
Disk space for uploaded files (or S3 storage)
A domain name (optional but recommended)

Docker Compose Configuration

Create a directory for Gokapi:

mkdir -p ~/gokapi && cd ~/gokapi

Create a docker-compose.yml file:

services:
  gokapi:
    image: f0rc3/gokapi:v2.2.4
    container_name: gokapi
    ports:
      - "127.0.0.1:53842:53842"
    volumes:
      - gokapi-data:/app/data
      - gokapi-config:/app/config
    restart: unless-stopped

volumes:
  gokapi-data:
  gokapi-config:

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server-ip:53842 in your browser.
The setup wizard runs on first launch:
- Set your admin email and password (email is used as the super admin identifier)
- Choose the storage backend: local (default) or S3/S3-compatible
- Set the server URL (your domain or IP)
- Configure encryption (optional — enables end-to-end encryption for stored files)
- Set minimum password length
Log in to the admin dashboard.
Upload your first file and configure its expiry settings.

If upgrading from Gokapi v1.x, set the GOKAPI_ADMIN_USER environment variable to your email address before starting the container. The config.json file must be writable. Downgrading from v2 to v1 is not possible.

Configuration

Upload Settings

When uploading a file through the admin UI, configure:

Downloads allowed: Number of times the file can be downloaded before auto-deletion
Expiry days: Number of days before the file expires
Password protection: Optional password for the download link
Unlimited downloads: Disable download count limit
No expiry: File never expires automatically

API Uploads

Gokapi provides an API for programmatic uploads. Get your API key from the admin dashboard under API Keys:

curl -X POST "https://your-domain.com/api/files/add" \
  -H "apikey: your-api-key" \
  -F "file=@document.pdf" \
  -F "allowedDownloads=10" \
  -F "expiryDays=7" \
  -F "password=optional-password"

Multi-User Management (v2.0+)

Gokapi v2 supports multiple users with granular permissions. The super admin (set via GOKAPI_ADMIN_USER env var or during setup) manages user accounts from the admin dashboard:

Create users with email-based authentication
Assign permissions per user (upload, view, delete, API key management)
Restrict user groups to specific file access
Integrate with OIDC identity providers (Authentik, Keycloak) for centralized auth

To hide the API menu from non-admin users, set DISABLE_API_MENU=true.

File Requests (v2.2+)

Generate a URL that lets external users upload files to your Gokapi instance without an account. Useful for collecting files from clients or collaborators. Uploads through file requests are visible only to the user who created the request.

Environment Variable	Default	Description
`GOKAPI_GUEST_UPLOAD_BY_DEFAULT`	`false`	Grant file request permissions to users on upgrade
`GOKAPI_MAX_FILES_GUESTUPLOAD`	`100`	Max files per file request
`GOKAPI_MAX_SIZE_GUESTUPLOAD`	`10 GB`	Max file size for file request uploads

Hotlink Protection

Gokapi can generate hotlinks — direct URLs to the file content instead of the download page. Useful for embedding images or sharing direct download links. Note: SVG hotlinks were removed in v2.2.3 for security reasons (stored XSS vulnerability).

Advanced Configuration (Optional)

S3 Storage Backend

Store files in any S3-compatible service (AWS S3, MinIO, Backblaze B2):

During the setup wizard, choose “AWS S3” as the storage backend and provide:

Bucket name
Region
Access key ID
Secret access key
Endpoint (for non-AWS S3-compatible services like MinIO)

S3 storage is ideal for large file volumes or when you want files to persist independently of the Docker container.

End-to-End Encryption

Gokapi supports optional end-to-end encryption for stored files. Enable during setup or in the admin settings:

Files are encrypted before storage using AES-256
Encryption keys are stored in the config volume
Encrypted files cannot be read from the filesystem or S3 bucket directly

OAuth2/OIDC Authentication

Gokapi supports OAuth2 and OIDC for admin authentication, integrating with Authentik, Keycloak, or other identity providers. Configure during setup or in config.json.

Trusted Proxies

If running behind a reverse proxy that does not connect from 127.0.0.1, set the trusted proxy list:

environment:
  GOKAPI_TRUSTED_PROXIES: "10.0.0.0/8,172.16.0.0/12"  # Your proxy subnet
  # GOKAPI_USE_CLOUDFLARE: "true"  # Enable if behind Cloudflare

Docker subnets are automatically trusted as of v2.2.2. To disable this, set GOKAPI_DISABLE_DOCKER_TRUSTED_PROXY=true.

CLI Tool

Gokapi provides a dedicated CLI tool (gokapi-cli) for scripted uploads with end-to-end encryption and folder upload support:

gokapi-cli upload --server https://share.example.com --apikey your-key document.pdf

Reverse Proxy

Behind Caddy (Reverse Proxy Setup):

share.example.com {
    reverse_proxy localhost:53842
}

Update the server URL in Gokapi’s admin settings to match your domain after setting up the reverse proxy.

Backup

Back up these volumes:

gokapi-config — Configuration, encryption keys, database
gokapi-data — Uploaded files (skip if using S3)

# Backup both volumes
for vol in gokapi-config gokapi-data; do
  docker run --rm -v ${vol}:/data -v $(pwd):/backup alpine \
    tar czf /backup/${vol}-$(date +%Y%m%d).tar.gz /data
done

Important: If using encryption, the config volume contains the encryption keys. Losing the config volume means losing access to encrypted files — even if the data volume or S3 bucket is intact.

See Backup Strategy for a complete approach.

Troubleshooting

Setup wizard keeps reappearing

Symptom: Every restart shows the setup wizard instead of the login page. Fix: Ensure the gokapi-config volume persists. Check docker volume ls | grep gokapi-config. If missing, the config was lost — run setup again.

S3 upload fails

Symptom: File uploads fail with S3-related errors. Fix: Verify your S3 credentials and bucket permissions. The bucket must allow PutObject, GetObject, and DeleteObject. For MinIO, ensure the endpoint URL includes the port.

Files not auto-deleting

Symptom: Expired files remain accessible. Fix: Gokapi checks expiry on access, not on a schedule. Files are deleted when someone attempts to download them after expiry, or during periodic cleanup. This is by design.

Large file upload timeout

Symptom: Files over 1 GB fail to upload. Fix: Check reverse proxy timeouts and upload size limits. For Nginx: client_max_body_size 0; and proxy_read_timeout 600;. Caddy has no default limits.

Resource Requirements

RAM: ~30-50 MB idle
CPU: Low
Disk: ~20 MB for the application, plus storage for uploaded files

Verdict

Gokapi is the best middle-ground file sharing tool. It’s more capable than PicoShare (adds S3 support, encryption, multi-user, API, password protection, file requests) without the complexity of Send (no Redis required). The v2 release added multi-user support, file requests, a CLI tool, rate limiting, and several security fixes — making it viable for small teams, not just solo use. The admin dashboard is clean, the API is straightforward, and S3 storage support is a significant advantage for large-volume use.

If you need end-to-end encryption with zero-knowledge design, use Send. If you want absolute minimalism, use PicoShare. Gokapi sits between them and handles most file sharing needs elegantly.

Frequently Asked Questions

Is Gokapi multi-user?

Yes, as of v2.0. Gokapi supports multiple users with granular permissions. The super admin manages accounts, and each user can have different upload/view/delete permissions. Prior to v2.0, it was single-admin only.

Can I use Gokapi with ShareX?

Yes, via the API. Configure ShareX’s custom uploader to POST to /api/files/add with your API key header. Note: in v2.0+, API keys are always required — session-based auth was removed.

Does Gokapi support chunked uploads?

Yes. The API supports chunked uploads with a minimum chunk size of 5 MB (except the final chunk). The web UI handles chunking automatically for large files. Use S3 storage for very large file volumes.

Can external users upload files to Gokapi?

Yes, via File Requests (v2.2+). Generate a shareable upload URL from the admin dashboard. External users can upload without an account, and files appear only for the request creator.