jessieh/simple-shortener
jessieh/simple-shortener
1
Fork 0
mirror of https://gitlab.com/jessieh/simple-shortener.git synced 2024-11-25 12:21:45 +00:00
Code Releases Activity

Revert "Fix strange bug with GitLab asset links in README"

Browse Source 
This reverts commit b1bd9f9b40.
This commit is contained in:
Jessie Hildebrandt 2022-02-02 00:31:43 -05:00
parent b1bd9f9b40
commit b00397a284
1 changed files with 0 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
README.md
View File

@ -1,163 +0,0 @@
# <img src="../../raw/assets/icon.png" width=75> simple-shortener
Easily wrap a self-hosted URL shortening service around your personal site.
[View on Docker Hub](https://hub.docker.com/r/jessiehildebrandt/simple-shortener)
Created with [Fennel](https://fennel-lang.org), [Turbo](https://github.com/kernelsauce/turbo), and [Mithril](https://mithril.js.org/).
[![Build Status](https://gitlab.com/jessieh/simple-shortener/badges/main/pipeline.svg)](https://gitlab.com/jessieh/simple-shortener/-/pipelines)
## Table of Contents
- [Demo](#demo)
- [Deploying](#deploying)
- [Configuration](#configuration)
- [API](#documentation)
- [TOTP Issuer Icons](#totp-issuer-icons)
## Demo
<img src="../../raw/assets/demo.png">
## Deploying
**NOTE**: You will need to configure `auth_secret` before the service will run. See **[Configuration](#configuration)**.
With Docker<sup>1</sup>:
```bash
docker run -d \
-p 80:80 \
--env-file config.env \
--mount source=shortener-db,target=/simple-shortener/db \
--mount type=bind,source=/PATH/TO/YOUR/SITE,target=/simple-shortener/static/landing_page,readonly \
jessiehildebrandt/simple-shortener
```
With Docker Compose<sup>1</sup>:
```yaml
simple-shortener:
image: jessiehildebrandt/simple-shortener
env_file: config.env
ports:
- 80:80
volumes:
- shortener-db:/simple-shortener/db
- /PATH/TO/YOUR/SITE:/simple-shortener/static/landing_page:ro
volumes:
shortener-db:
```
After deploying, you should be able to navigate your browser to `<YOUR_DOMAIN>` to view your site, or `<YOUR_DOMAIN>/shorten` to log in to the control panel. If you have TOTP auth enabled (on by default), check your Docker logs for a QR code to scan with your TOTP generator app of choice. If you disabled TOTP auth, you can log in by entering `auth_secret` as the passcode.
<sup>1</sup> You should probably avoid directly exposing the Turbo HTTP server as in these examples, and should instead opt to use a more robust server as a reverse-proxy.
## Configuration
You can easily configure your deployment by supplying an environment variable file with your desired settings.
An [example environment variable file](config_template.env) is provided for use as a template.
Supported configuration options:
### auth_secret ***(REQUIRED)***
**string**
*THIS VALUE NEEDS TO BE SET BEFORE THE SERVICE WILL START!*
This is used to authenticate sessions for the shortener control panel and the REST API.
Depending on configuration, this can either be used as a TOTP secret or as a password.
### enable_control_panel
**boolean**
Whether or not a static control panel page for interacting with the shortening service will be exposed at `/shorten`.
Default `true`
### enable_landing_page
**boolean**
Whether or not a static landing page will be served when not visiting shortened links or the control panel.
Default `true`
### landing_page_index
**string**
The path to the file to use as the index for the landing page.
*This only has an effect when `enable_landing_page` is set to true.*
Default `index.html`
### listen_port
**number**
The port that the HTTP server will listen on.
Default `80`
### query_limit
**number**
The maximum number of database entries that the API will return in a single query.
Default `100`
### session_max_length_hours
**number**
The duration (in hours) that an API session will be valid for once signed in, regardless of activity.
Default `24`
### session_max_idle_length_hours
**number**
The duration (in hours) that an API session will be valid for without any activity.
Default `1`
### use_secure_cookies
**boolean**
Whether or not to tag API session cookies with the `Secure` and `SameSite=Strict` attributes.'
Secure cookies expect your server to have HTTPS enabled, and will prevent the control panel and API from functioning over unsecured connections.
Default `true`
### use_totp
**boolean**
Whether or not `auth_secret` will be used as a TOTP secret instead of a password.
If enabled, the server will print a QR code to stdout containing a standardized URL that you can scan with most TOTP generators.
(TOTP is recommended, but you may want to disable it if (e.g) your system cannot be synchronized to global time.)
Default `true`
## API
The shortening service exposes a simple API at `/shorten/api` that you may consume from your own control panel<sup>1</sup>, a browser extension, etc.
The API endpoints and response codes are documented in the docstrings of their respective [handler modules](src/handlers).
<sup>1</sup> If you wish to replace the default control panel, you can provide your own by mounting it at `/simple-shortener/static/control_panel`.
## TOTP Issuer Icons
Should your TOTP provider application of choice support them, the following issuer icons are available for use.
### SVG
<img src="../../raw/assets/simple-shortener.svg" width=75>&nbsp;<img src="../raw/assets/simple-shortener bg.var.svg" width=75>
### PNG
<img src="../../raw/assets/simple-shortener.png" width=75>&nbsp;<img src="../raw/assets/simple-shortener bg.var.png" width=75>