Skip to content

Self‐Hosting

Jump to bottom
Neotamandua edited this page May 1, 2024 · 6 revisions

Here you can find extensive documentation on how to self-host hdrop.

General Information

  • The frontend and backend can be deployed separately
    • There is nothing stopping you from deploying both on the same server though
  • Hdrop uses environment variables for configuration (both frontend and backend)
  • Hdrop comes with sane and secure defaults, so you won't have to touch most env variables

Environment Variables

hdrop has lots of env variables for configuration purposes. During a typical installation, you will only use a small subset of the available variables, so don't be afraid of the huge number of available options!

Frontend

Name Example Value Description
NEXT_PUBLIC_APP_NAME hdrop Display name of the instance
NEXT_PUBLIC_WEB_BASE_URL http://localhost:3000 The URL where the frontend is hosted
NEXT_PUBLIC_API_BASE_URL http://localhost:8080 The URL where the API is hosted
NEXT_PUBLIC_PBKDF2_ITERATIONS 600000 Number of PBKDF2 passes on the password
NEXT_PUBLIC_PASSWORD_BYTES 32 Number of bytes in the password
NEXT_PUBLIC_CHALLENGE_BYTES 32 Number of bytes in the challenge

⚠️ Required: NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_WEB_BASE_URL, NEXT_PUBLIC_API_BASE_URL
Everything else is fully optional and already comes with safe and secure defaults.

Backend

The backend has a lot of env variables for configuration, but you will typically only use a few of them.

Name Example Description Required Default
HDROP_PORT 2000 Hdrop Listener port No 8080
PROMETHEUS_PORT 4000 Prometheus port No 3001
DATABASE_URL postgres://user:pass@host/db Postgres Connection String Yes -
STORAGE_PROVIDER s3 / local Storage provider Yes -
S3_REGION example-region-1 S3 region No -
S3_ENDPOINT https://foo.s3.example.org S3 endpoint No -
S3_ACCESS_KEY_ID AKIAIOSFODNN7EXAMPLE S3 Access Key ID No -
S3_SECRET_ACCESS_KEY bPxRfiCYEXAMPLEKEY S3 Secret Access Key No -
S3_PUBLIC_URL https://storage.example.org S3 Public Bucket URL No -
S3_BUCKET_NAME hdrop S3 Bucket Name No -
LOCAL_STORAGE_DIR /var/hdrop-storage Local storage path No ./files
LOCAL_STORAGE_LIMIT_MB 250 Local storage limit in MB No -
SINGLE_FILE_LIMIT_MB 250 File upload limit[^5] No 100
CORS_ORIGIN * / example.com,foo.bar Allowed CORS origins No *
CACHE_STRATEGY memory / disk / hybrid Cache strategy No memory
CACHE_MEMORY_LIMIT_MB 250 Cache memory limit in MB No -
CACHE_DISK_LIMIT_MB 250 Cache disk limit in MB No -
CACHE_DIR /var/cache Cache storage directory No ./file_cache

Minimal local example

Let's build an absolutely minimal backend configuration, to show how simple it can be.

We're building the following configuration:

  • Server listens on default port (unspecified = 8080)
  • Use a local Postgres instance (example connection string)
  • Use a local storage provider with a capacity of 1 GB
  • Use an unbounded in-memory cache
  • Use the default CORS settings (unspecified = any origin)
DATABASE_URL=postgres://testuser:testpass@localhost/hdrop
STORAGE_PROVIDER=local
LOCAL_STORAGE_DIR=/tmp/cache
LOCAL_STORAGE_LIMIT_MB=1000
CACHE_STRATEGY=memory

Minimal S3 example

We're building the following configuration:

  • Server listens on default port (unspecified = 8080)
  • Use a local Postgres instance (example connection string)
  • Use the S3 storage provider
  • Use an unbounded in-memory cache
  • Use the default CORS settings (unspecified = any origin)
DATABASE_URL=postgres://testuser:testpass@localhost/hdrop
STORAGE_PROVIDER=s3
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=bPxRfiCYEXAMPLEKEY
S3_ENDPOINT=s3.us-east-1.amazonaws.com
S3_PUBLIC_URL=my-hdrop-bucket.example.org
S3_BUCKET_NAME=hdrop
CACHE_STRATEGY=memory

Deploying to Baremetal

This section is a work-in-progress.

Deploying to the Cloud

Frontend

The frontend is written in Next.js and generally super simple to deploy. Any modern cloud hosting provider will do, but we also support Docker.

Vercel

  1. Fork the repo
  2. Create a new Vercel project and link it to your fork
  3. Set the root directory to hdrop-web-next
  4. Configure the relevant environment variables
  5. Deploy and enjoy!

Other Providers

Deploying to other providers should be similarly simple. Just be sure to configure the environment variables listed above.

Backend

Generic (Docker)

Prerequisites

  • Postgres database
  • S3-compatible object store or available disks
    Examples of compatible providers include:
    • Amazon S3
    • Cloudflare R2
    • Backblaze B2

We provide a preconfigured Dockerfile with pm2. Simply deploy the Dockerfile in hdrop-server to your server. As always, be sure to configure the environment variables as needed!

DigitalOcean

This section is a work-in-progress...

Clone this wiki locally