Akasio is a simple HTTP server that redirects traffic based on a JSON redirect table.
If you own a domain and wish to self-host a URL-shortening service, then this is the right tool for you.
Originally, Akasio is a backend server for website akas.io (akas stands for “also known as”) written in Python and Flask. After rewriting the server with Golang, I decided to open-source it for anyone else that might be interested by it. It is both very easy to deploy and very easy to maintain, thanks to Golang’s handy single-binary release (let’s not talk about its size here).
What can this be used for?
Personally, I find sending long URLs like https://gist.githubusercontent.com/k4yt3x/3b41a1a65f5d3087133e449793eb8858/raw to people pretty annoying, since you’ll either have to copy and paste the whole URL or type the whole URL out. URL shorteners like Akasio solve this issue. All that’s needed to be done to send such a long URL is just to create a new mapping in the redirect table (akas.io/z).
What are Akasio’s benefits compared to services like bit.ly?
Akasio is self-hosted, and the redirect table is just a JSON file. This gives the users lots of flexibilities. The JSON file on the server can be symbolic-linked from a local workstation, updated by a front-end webpage, generated from a program, and so on.
This section covers Akasio’s fundamental concepts, basic usages and setup guide.
Akasio redirects incoming requests based on what’s called a “redirect table”. This table is essentially a JSON file with a simple source-to-target mapping. You can find an example akasio.json under the configs directory. By default, Akasio reads the redirect table from /etc/akasio.json.
{
"/": "http://k4yt3x.com/akasio-go",
"/g": "https://github.com/k4yt3x",
"/k4yt3x": "https://k4yt3x.com"
}
This example redirect table does the following mappings:
/ to http://k4yt3x.com/akasio-go//g to https://github.com/k4yt3x/k4yt3x to https://k4yt3x.comTaking the /g mapping for example, when a user visits https://yourwebsite.com/g, the user will be redirected to https://github.com/k4yt3x via a HTTP 301 (moved permanently) response.
When Akasio receives a request, it chops the request’s path into segments, looks up the first segment against the redirect table, and returns the target URL + the rest of the segments joined with /.
For example, if the request URI is /segment1/segment2/segment3, the URI will be split into a string array with elements segment1, segment2, and segment3. Akasio will then lookup /segment1 within the redirect table and return redirected target URL + /segment2/segment3. If a / is not present at the end of the target URL, one will be appended automatically.
Continuing the example in the previous section, if the user visits https://yourwebsite.com/g/akasio-go, the user will be redirected to https://github.com/k4yt3x/akasio-go.
The recommended setup is to start Akasio as a service behind reverse proxy web server like Apache, Nginx or Caddy. You can find an example service file at configs/akasio.service.
A typical stand-alone setup process will look like the following.
akasio binary or download the akasio binary from releases.akasio binary to /usr/local/bin/akasio./etc/systemd/system/akasio.service.systemctl daemon-reload.systemctl enable --now akasio.curl -v 127.0.0.1:8000.The binary’s usage is as following. You can also invoke akasio -h to see the usages.
Usage:
-b string
binding address (IP:port) (default "127.0.0.1:8000")
-d enable debugging mode, which disables security checks
-n value
server hostname, can be specified multiple times
-r string
redirect table path (default "/etc/akasio.json")
-v print Akasio version and exit
The command below, for instance, launches Akasio, reads configurations from the file /etc/akasio.json, and serves domains akas.io and ffg.gg.
/usr/local/bin/akasio -r /etc/akasio.json -n akas.io -n ffg.gg
Akasio is also available on Docker Hub. Below is an example how you can run Akasio with Docker. Be sure to create the redirect table and change the redirect table’s path in the command below. You’ll also need to change the server’s hostname.
docker run -it -p 8000:8000 -v $PWD/akasio.json:/etc/akasio.json -h akasio --name akasio k4yt3x/akasio-go:1.1.1 -n akas.io
docker run -it \ # interactive
-p 8000:8000 \ # bind container port to host's port 8000
-v $PWD/akasio.json:/etc/akasio.json \ # bind mount host's akasio.json file under the current directory to container's /etc/akasio.json
-h akasio \ # set container hostname akasio
--name akasio \ # set container name akasio
k4yt3x/akasio-go:1.1.1 \ # container name
-n akas.io # listening hostnames
After spinning the container up, you can verify that it’s running correctly by making a query with curl or any other tool of your preference.
The following commands will build Akasio binary at bin/akasio.
git clone https://github.com/k4yt3x/akasio-go.git
cd akasio-go
make
After building, you may also use sudo make install to install akasio to /usr/local/bin/akasio.