diff options
Diffstat (limited to 'README.adoc')
| -rw-r--r-- | README.adoc | 103 |
1 files changed, 0 insertions, 103 deletions
diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 00ac6ac..0000000 --- a/README.adoc +++ /dev/null | |||
| @@ -1,103 +0,0 @@ | |||
| 1 | = Shrt | ||
| 2 | |||
| 3 | A naively simple URL shortener | ||
| 4 | |||
| 5 | image::screenshot-0.webp[Screenshot] | ||
| 6 | |||
| 7 | image::screenshot-1.webp[Screenshot] | ||
| 8 | |||
| 9 | == Installation | ||
| 10 | |||
| 11 | Only *NIX systems are supported. | ||
| 12 | |||
| 13 | Runtime dependencies: | ||
| 14 | |||
| 15 | - cURL | ||
| 16 | - OpenSSL | ||
| 17 | - SQLite | ||
| 18 | |||
| 19 | Build dependencies: | ||
| 20 | |||
| 21 | - CMake | ||
| 22 | - A C++23 compiler | ||
| 23 | |||
| 24 | === Building from source | ||
| 25 | |||
| 26 | 1. Clone the repo | ||
| 27 | 2. Go into the repo directory, and run `cmake -B build`. | ||
| 28 | 3. Run `cmake --build build -j`. | ||
| 29 | 4. Pick a data directory where the database will be created. | ||
| 30 | 5. Copy the `templates` and `statics` directories into the data | ||
| 31 | directory. | ||
| 32 | 6. Copy `build/shrt` into any directory that is in your `$PATH`. | ||
| 33 | |||
| 34 | === Using pre-build binary | ||
| 35 | |||
| 36 | 1. Download the binary from one of the releases. | ||
| 37 | 2. Extract the downloaded tarball. | ||
| 38 | 3. Continue to step 4 in “Building from source”. | ||
| 39 | |||
| 40 | === Arch Linux package | ||
| 41 | |||
| 42 | A PKGBUILD is provided in `packages/arch` in this repository. | ||
| 43 | |||
| 44 | == Configuartion | ||
| 45 | |||
| 46 | By default, shrt looks for a configuration file at `/etc/shrt.yaml`. | ||
| 47 | This path can be changed with the `-c` command line option. An example | ||
| 48 | configuration file is printed below with comments. | ||
| 49 | |||
| 50 | [source,yaml] | ||
| 51 | ---- | ||
| 52 | # Specify the data directory you have picked. | ||
| 53 | data-dir: "/var/lib/shrt" | ||
| 54 | # The listening address. Example: localhost, 0.0.0.0, 127.0.0.1. | ||
| 55 | listen-address: localhost | ||
| 56 | # The port to listen to. If this is 0, the value of “listen-address” | ||
| 57 | # is treated as a path of a UNIX domain socket file. | ||
| 58 | listen-port: 8080 | ||
| 59 | # The client ID of your shrt service. This is given by the OpenID | ||
| 60 | # Connect provider. | ||
| 61 | client-id: shrt | ||
| 62 | # The client secrete of your shrt service. This is given by the OpenID | ||
| 63 | # Connect provider. | ||
| 64 | client-secret: "abced12345" | ||
| 65 | # The initial URL of the OpenID Connect service. | ||
| 66 | openid-url-prefix: "https://auth.example.com/" | ||
| 67 | # The base URL of your shrt service. This is usually just “https://” | ||
| 68 | # followed by your domain name. | ||
| 69 | base-url: https://go.mws.rocks | ||
| 70 | ---- | ||
| 71 | |||
| 72 | === Authentication | ||
| 73 | |||
| 74 | Shrt relies on an external OpenID Connect service provider for | ||
| 75 | authentication. Usually you register your instance of shrt to the | ||
| 76 | OpenID Connect provider. The provider will give you an client ID and a | ||
| 77 | client secret (in this case your shrt server is the “client” of the | ||
| 78 | OpenID Connect service). An OpenID Connect service has a number of | ||
| 79 | endpoints, such as user info, tokens, etc. The URLs of those endpoints | ||
| 80 | are discover by visiting a URL that is constructed from the URL in the | ||
| 81 | configuration option `openid-url-prefix`, followed by | ||
| 82 | `.well-known/openid-configuration`. For example, if you set | ||
| 83 | `openid-url-prefix` to be `https://auth.example.com/`, the resulting | ||
| 84 | URL would be | ||
| 85 | |||
| 86 | ---- | ||
| 87 | https://auth.example.com/.well-known/openid-configuration | ||
| 88 | ---- | ||
| 89 | |||
| 90 | This method works on KeyCloak, but I have never tested this on other | ||
| 91 | OpenID Connect providers. | ||
| 92 | |||
| 93 | === Base URL and shortcuts | ||
| 94 | |||
| 95 | For the configuration option `base-url`, usually this is just | ||
| 96 | `https://` followed by a domain that you own. Supposed you create a | ||
| 97 | shortcut called “search” which points to `https://google.com`, you | ||
| 98 | would be able to visit `https://your.domain/search` and be redirected | ||
| 99 | to `https://google.com`. However you do not have to use a root URL | ||
| 100 | under your domain. If you set `base-url` to | ||
| 101 | `https://your.domain/some/path`, your shortcut would be at | ||
| 102 | `https://your.domain/some/path/search`. I do not know why anybody | ||
| 103 | would want this, but the capability is there. | ||