chela/README.md

Chela

Chela is a minimal URL shortener built in Rust. It is named after the small claw on crustaceans.

Usage

You can create a redirect by navigating to the /create page and filling out the form. By default, every path passed to Chela will be treated as a redirect except / and /create.

Install and Run

With Docker

CLI

$ docker run -d \
    -p 3000:3000 \
    -e DATABASE_URL=postgres://chela:password@dbhost/postgres?sslmode=disable \
    -e CHELA_HOST=a.com \
    secondsmiles/chela

Docker Compose

services:
    chela-postgres:
        image: postgres:15
        environment:
            - POSTGRES_USER=chela
            - POSTGRES_PASSWORD=password
        volumes:
            - chela-db:/var/lib/postgresql/data
        restart: unless-stopped
    chela:
        image: secondsmiles/chela
        ports:
            - 3000:3000
        environment:
            - DATABASE_URL=postgres://chela:password@chela-postgres/postgres?sslmode=disable
            - CHELA_HOST=a.com
            - CHELA_MAIN_PAGE_REDIRECT='https://example.com'
            - CHELA_BEHIND_PROXY=1
        depends_on:
            - chela-postgres
        restart: unless-stopped

volumes:
    chela-db:

Environment Variables

DATABASE_URL

Used to define the database connection for Chela to use.

CHELA_HOST

The hostname that Chela should refer to itself as. Defaults to localhost.

CHELA_LISTEN_ADDRESS

The address that Chela should listen on. Defaults to 0.0.0.0.

CHELA_MAIN_PAGE_REDIRECT

A page that Chela will redirect to when / is requested instead of replying with the default homepage.

CHELA_BEHIND_PROXY

If this variable is set, Chela will use the X-Real-IP header as the client IP address rather than the connection address.

CHELA_UNIX_SOCKET

If you would like Chela to listen for HTTP requests over a Unix socket, set this variable to the socket path that it should use. By default, Chela will listen via a Tcp socket.

CHELA_ALPHABET

If this variable is set, Chela will use the characters in CHELA_ALPHABET to create IDs for URLs. The default alphabet is abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ. See here for more information on Sqids alphabets.

Manually

Build

$ git clone https://github.com/secondary-smiles/chela.git
$ cd chela
$ cargo build -r

Run

$ export DATABASE_URL=postgres://chela:password@dbhost/postgres?sslmode=disable
$ export CHELA_HOST=a.com
$ export CHELA_LISTEN_ADDRESS=127.0.0.1
$ ./target/release/chela

Hosting

Chela uses the axum to manage HTTP requests, so it is possible to expose it directly to the outer internet. However, there is no authentication for the /create endpoint so anyone will be able to create redirects.

If you would prefer to be the only one able to create redirects, then you can proxy Chela through Nginx with http-basic-auth. Refer to this documentation for more information.

server {
    server_name example.com;
    
    location / {
        proxy_pass http://localhost:3000/;
        proxy_set_header X-Real-IP $remote_addr;

        limit_except GET HEAD {
            auth_basic 'Restricted';
            auth_basic_user_file /path/to/your/.htpasswd;
        }
    }
}