Shav Kinderlehrer
a4cfb64155
Some checks failed
Build and Push Docker Image / docker (push) Has been cancelled
120 lines
4.2 KiB
Markdown
120 lines
4.2 KiB
Markdown
[](https://github.com/secondary-smiles/chela/actions/workflows/docker-image.yml)
|
|
[](https://hub.docker.com/r/secondsmiles/chela)
|
|
|
|
# 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`.
|
|
|
|
Chela also supports basic analytics for shortened URLs. This page is available at `/tracking`, and `/tracking/<URL ID>`.
|
|
|
|
## Install and Run
|
|
### With Docker
|
|
#### CLI
|
|
```bash
|
|
$ 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
|
|
```yaml
|
|
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](https://sqids.org/faq#unique) for more information on Sqids alphabets.
|
|
|
|
##### `CHELA_USES_HTTPS`
|
|
If this variable is set, Chela will refer to itself as `https://$CHELA_HOST` instead of the default `http://$CHELA_HOST`.
|
|
|
|
### Manually
|
|
#### Build
|
|
```bash
|
|
$ git clone https://github.com/secondary-smiles/chela.git
|
|
$ cd chela
|
|
$ cargo build -r
|
|
```
|
|
|
|
#### Run
|
|
```bash
|
|
$ 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](https://crates.io/crates/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` or `/tracking` endpoints so anyone will be able to create redirects and view analytics.
|
|
|
|
If you would prefer to be the only one able to access these pages, then you can proxy Chela through Nginx with http-basic-auth. Refer to [this](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/) documentation for more information.
|
|
|
|
```nginx
|
|
server {
|
|
server_name a.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;
|
|
}
|
|
}
|
|
|
|
location /tracking {
|
|
proxy_pass http://localhost:3000$request_uri;
|
|
|
|
auth_basic 'Restricted';
|
|
auth_basic_user_file /path/to/your/.htpasswd;
|
|
}
|
|
}
|
|
```
|