hudik/hoodik repository overview

⁠Hoodik

Hoodik is a lightweight, self-hosted, end-to-end encrypted cloud storage server. All encryption and decryption happens in your browser — the server never sees your plaintext data. Built with Rust (Actix-web) on the backend and Vue 3 on the frontend.

🌐 hoodik.io⁠ — Website  |  📱 Android App⁠  |  ⚡ VPS Setup Guide⁠

⁠Features

• End-to-end encryption — files are encrypted in the browser before upload and decrypted after download using a hybrid RSA + AEGIS-128L scheme
• Secure search — file metadata is tokenized and hashed so the server can match search queries without storing plaintext names
• Encrypted notes — create and edit rich markdown notes with a WYSIWYG editor; content is encrypted, auto-saved, and searchable just like uploaded files
• Public sharing links — share files via a link; the file key is never exposed to the recipient
• Two-factor authentication — optional TOTP-based 2FA per user
• Admin dashboard — manage users, sessions, invitations, and application settings
• Chunked transfers — files are split into encrypted chunks for concurrent upload/download
• SQLite or PostgreSQL — SQLite out of the box, PostgreSQL via a single environment variable
• S3-compatible storage — store encrypted chunks on any S3-compatible service (AWS, MinIO, Backblaze B2, Wasabi) instead of local disk
• Docker-first — single container deployment; multi-arch images (amd64, armv6, armv7, arm64)

⁠How encryption works

⁠File storage

Each user gets an RSA-2048 key pair on registration. The private key is stored encrypted with your passphrase — the server cannot read it.

When you upload a file:

1. A random symmetric key is generated for the file (key size depends on the cipher).
2. The file is encrypted chunk-by-chunk with that key using the file's cipher (default: AEGIS-128L).
3. The cipher identifier and the encrypted key are stored in the database alongside the file, so old files can always be decrypted with the correct algorithm even after the default cipher changes.

⁠Search

Searchable metadata (file name, etc.) is tokenized, hashed, and stored as opaque tokens. When you search, the same operation is applied to your query and the hashes are matched server-side — no plaintext ever leaves the browser.

⁠Public links

When you share a file:

1. A random link key is generated.
2. The file metadata and file key are encrypted with the link key.
3. The link key itself is encrypted with your RSA public key (so you can always recover it).
4. The link key is appended to the share URL as a fragment: https://…/links/{id}#link-key.

The recipient's browser uses the fragment to decrypt the file key locally. The server only ever sees encrypted bytes.

⁠Cryptographic primitives

The cipher used to encrypt each file is stored in the database (files.cipher), so the correct algorithm is always used for decryption regardless of what the current default is.

⁠Getting started

⁠Docker (quickstart)

docker run --name hoodik -d \
  -e DATA_DIR='/data' \
  -e APP_URL='https://my-app.example.com' \
  --volume "$(pwd)/data:/data" \
  -p 5443:5443 \
  hudik/hoodik:latest

This runs with a self-signed TLS certificate generated automatically in DATA_DIR. For production, provide your own certificate (see Configuration⁠) or put Hoodik behind a reverse proxy such as Nginx Proxy Manager⁠.

⁠Docker with email and custom TLS

docker run --name hoodik -d \
  -e DATA_DIR='/data' \
  -e APP_URL='https://my-app.example.com' \
  -e SSL_CERT_FILE='/data/my-cert.crt.pem' \
  -e SSL_KEY_FILE='/data/my-key.key.pem' \
  -e MAILER_TYPE='smtp' \
  -e SMTP_ADDRESS='smtp.gmail.com' \
  -e SMTP_USERNAME='[email protected]' \
  -e SMTP_PASSWORD='your-app-password' \
  -e SMTP_PORT='465' \
  -e SMTP_DEFAULT_FROM_EMAIL='[email protected]' \
  -e SMTP_DEFAULT_FROM_NAME='Hoodik Drive' \
  --volume "$(pwd)/data:/data" \
  -p 5443:5443 \
  hudik/hoodik:latest

⁠Configuration

All configuration is done through environment variables. A full reference is in .env.example⁠.

⁠Core

⁠TLS

⁠Authentication & sessions

⁠Cross-domain / multi-domain setups — USE_HEADERS_FOR_AUTH

By default, Hoodik uses HttpOnly cookies for authentication. If your frontend and backend are on different domains (or you want to access the API from a separate app), cookies won't work reliably. Set:

USE_HEADERS_FOR_AUTH=true

With this enabled:

• The server issues tokens via response headers instead of cookies.
• The browser stores the tokens in localStorage rather than HttpOnly cookies, making them accessible to JavaScript.
• Each request must include the token in the Authorization: Bearer <token> header.

⁠Email (SMTP)

When MAILER_TYPE=none (the default), accounts are activated automatically and no emails are sent. Set MAILER_TYPE=smtp to enable email verification and file-share notifications.

⁠Storage provider

By default, encrypted file chunks are stored on the local filesystem inside DATA_DIR. Set STORAGE_PROVIDER=s3 to use any S3-compatible object storage instead.

Example with MinIO:

docker run --name hoodik -d \
  -e DATA_DIR='/data' \
  -e APP_URL='https://my-app.example.com' \
  -e STORAGE_PROVIDER='s3' \
  -e S3_BUCKET='hoodik' \
  -e S3_ENDPOINT='http://minio:9000' \
  -e S3_ACCESS_KEY='minioadmin' \
  -e S3_SECRET_KEY='minioadmin' \
  -e S3_PATH_STYLE='true' \
  --volume "$(pwd)/data:/data" \
  -p 5443:5443 \
  hudik/hoodik:latest

⁠Migrating from local storage to S3

If you already have data stored locally and want to switch to S3:

1. Stop the running Hoodik instance.

2. Add the S3 environment variables to your docker-compose.yml (keep STORAGE_PROVIDER=local for now).

3. Run the migration:

   docker exec hoodik hoodik migrate-storage
   

   Copy

   Or as a one-off container:

   docker run --rm \
     -v hoodik-data:/data \
     -e DATA_DIR=/data \
     -e S3_BUCKET=my-bucket \
     -e S3_REGION=eu-central-1 \
     -e S3_ACCESS_KEY=... \
     -e S3_SECRET_KEY=... \
     hudik/hoodik migrate-storage
   

   Copy

   The command uploads all chunk files from DATA_DIR to S3. It is idempotent — already-uploaded files are skipped, so it is safe to re-run if interrupted.

4. Set STORAGE_PROVIDER=s3 and restart:

   docker compose up -d
   

   Copy

5. Verify everything works. The local chunk files can be kept as a backup until you are confident.

⁠Development

See DEVELOPMENT.md⁠ for setup instructions, available just recipes, testing, and CI.

⁠License

CC BY-NC 4.0⁠ — free for personal and non-commercial use. For commercial licensing, contact [email protected]⁠.

⁠Contributors

• Logo design by Nikola Matošević — Your Dear Designer⁠ ❤️