<h1 align="center">Hostling</h1>

Simple file hosting service

Main page | Library view | File modal | Admin panel :-------------------------:|:-------------------------:|:-------------------------:|:-------------------------: <img width="1280" height="900" alt="upload" src="https://files.catbox.moe/dfw4dv.png" /> | <img width="1280" height="900" alt="gallery" src="https://files.catbox.moe/6tj4bh.png" /> | <img width="1280" height="900" alt="modal" src="https://files.catbox.moe/9kbogh.png" /> | <img width="1280" height="900" alt="admin" src="https://files.catbox.moe/kjst5z.png" />

Features

• Login via Github and OpenID connect
• Account invite codes for enrolling new users
• Image automatic deletion, tagging, filtering, sorting
• Seperate upload tokens for automation setups (e.g scripts)
• Store data locally or on a S3/B2 bucket
• Sqlite and postgresql support
• File view count tracking

Usage

Deploy the service with either the nixos module or docker-compose then configure the service.

Have a look at the example configs in examples/

Config reference

Configuration is done via a TOML file (default: config.toml). Use the -c flag to specify a different location.

Setting up login providers

Login provider credentials are given only via env variables due to their sensitive nature.

• GITHUB_CLIENT_ID: GitHub OAuth application ID
• GITHUB_SECRET: GitHub OAuth application secret
• OPENID_CONNECT_CLIENT_ID: OpenID Connect client ID
• OPENID_CONNECT_CLIENT_SECRET: OpenID Connect client secret
• OPENID_CONNECT_DISCOVERY_URL: OpenID Connect discovery URL

Extra environment variables

• INITIAL_REGISTER_TOKEN: If set, uses this value as the initial admin registration token on first run instead of generating a random one. Useful for automated deployments and testing.

Config options

• data_folder: Directory for local file storage. Only used when S3 is not configured.
• max_upload_size: Maximum file upload size in bytes. Defaults to 100MB.
• database_type: Database type: "sqlite" or "postgresql" |
• database_connection_url: Database connection string. For SQLite: filename (e.g., "hostling.db"). For PostgreSQL: connection string (e.g., "host=localhost port=5432 user=postgres * sslmode=disable") |
• port: Port to run the HTTP server on (e.g., "8080") |
• unix_socket: Unix socket path to listen on instead of a TCP port (e.g., "/run/hostling/hostling.sock") |
• behind_reverse_proxy: Set to true if running behind a reverse proxy (nginx, Caddy, etc.) |
• trusted_proxy: Trusted proxy IP address. Used for rate limiting and IP detection. Required when hosting it from behind a reverse proxy.
• public_url: Public URL of the service. Required for GitHub OAuth callbacks. Include protocol and domain (e.g., "https://files.example.com") |
• branding: Custom branding text displayed in the interface. Maximum 20 characters. Defaults to "Hostling"
• tagline: Tagline for meta description and index page. Maximum 100 characters. Defaults to "Simple file hosting service"

Bucket storage setup

The below options will go in the [s3] section

• access_key_id: S3/B2 access key ID (can also be set via S3_ACCESS_KEY_ID environment variable)
• secret_access_key: S3/B2 secret access key (can also be set via S3_SECRET_ACCESS_KEY environment variable)
• bucket: S3/B2 bucket name (NOT the bucket ID)
• region: S3/B2 region (e.g., "us-east-1")
• endpoint: S3/B2 endpoint URL (e.g., "https://s3.us-west-002.backblazeb2.com")
• proxyfiles: More demanding option for serving s3 files to the user. In some cases its better to stream the content to the user instead of redirecting to the s3 presigned url, enable it only if you need it. (e.g files dont display properly without it)

Setup

Setup with NixOS module

<details> <summary><b>Setup with NixOS module</b></summary>

inputs = {
    hostling.url = "github:BatteredBunny/hostling?ref=v0.3.1";
};

imports = [ inputs.hostling.nixosModules.default ];

services = {
    hostling = {
        enable = true;
        createDbLocally = true;
        openFirewall = false;
        settings.database_type = "postgresql";
    };

    postgresql.enable = true;
};

</details>

Setup with docker

Have a look at docker-compose.yml

Development

Dev setup with nix

nix run .#test-service.driverInteractive
# run start_all()
# Then visit http://localhost:8839

Creating new sql migrations

Create migration for both sqlite and postgresql. Needs docker on your system.

just migration