mo8it/oxitraffic repository overview

⁠OxiTraffic

Self-hosted, simple and privacy respecting website traffic tracker 🌐

⁠➡️ Demo⁠ ⬅️⁠

⁠Source code on Codeberg 🏔️⁠

⁠Features

• ❌ Short visits are not counted
  • ✅ Only meaningful visits are counted
  • 🤖 Makes it less likely to count visits by web bots
• 🥷🏼 Respects privacy (no personal data or IP is logged)
• 🍪 No cookies
• 🕊️ Self-hosted
• 📈 Visualization of visits history
• 💻️ API for visits history and count
• 🏅 Low memory usage (about 12 MB)
• 📦️ First class container support
• 🔀 Asynchronous and multithreaded
• 📜 Informative tracing (logging) to stdout and to a log file
• 🆓 Free & open source (AGPLv3)
• 🦀 Written in Rust (oxidized)

⁠Demo

Here is a demo⁠ which tracks my own website (mo8it.com).

⁠How it works

You add the following script tag to your website after replacing OXITRAFFIC_BASE_URL with the base URL of your OxiTraffic instance:

<script type="module" src="https://OXITRAFFIC_BASE_URL/count.js"></script>

It runs the tiny script count.js⁠.

The script calls /register?path=PATH to receive a visitor ID. PATH is the path of the page you are on.

This ID is used after the minimum delay (configuration option min_delay_secs) to call /post-sleep/VISITOR_ID which leads to counting that visit.

When the page is left, a request is sent to /page-left/VISITOR_ID to record the total spent time.

⁠Path validation

How does OxiTraffic know if a newly requested path is a valid one for your tracked website?

Only for the first request to a new path, OxiTraffic sends a request to that path prefixed by the configuration option tracked_origin_callback. If the status code is in the range 200-299 (success), the path is added to the database. Otherwise, the request is rejected.

⁠Setup

⁠Containerized

You can use the container image published on Docker Hub⁠.

You can pull that image using Docker:

docker pull mo8it/oxitraffic:latest

Or using Podman:

podman pull docker.io/mo8it/oxitraffic:latest

The container image expects the config file to be mounted as a (read-only) volume at /volumes/config.toml inside the container (a volume doesn't have to be a directory, it can be a file).

You should mount an additional volume at /var/log/oxitraffic if you want to persist the logs.

By default, the container listens on port 80.

⁠Not containerized

You can also host OxiTraffic directly with the binary that you can install with Cargo:

cargo install oxitraffic --locked

Make sure to provide the environment variable OXITRAFFIC_CONFIG_FILE when using the binary directly (see the configuration section below).

⁠Database

In both cases (container or binary), you need a PostgreSQL database. There are many guides in the internet that explain how to host one either in a container or directly on the host. You could use my blog post about hosting PostgreSQL using Podman⁠.

⁠Configuration

The binary expects the environment variable OXITRAFFIC_CONFIG_FILE to point to the TOML configuration file config.toml. This environment variable is set to /volumes/config.toml in the container image.

The table below shows the configuration parameters for the configuration file. You can use environment variables to either set or overwrite parameters from the config file.

⁠Example configuration

This is an example of the configuration file config.toml:

# Can be omitted because this is the default value.
socket_address = "0.0.0.0:80"

base_url = "https://oxitraffic.your_domain.com"

tracked_origin = "https://your_domain.com"
# In case both OxiTraffic and your website are in a local network and `website` can be resolved to the local IP address of the your website.
# Omit this option to use the value of `tracked_origin` instead.
tracked_origin_callback = "http://website"

# You should omit this option when using the container image and mount a volume at the default directory `/var/log/oxitraffic` to persist logs.
logs_dir = "/home/USERNAME/oxitraffic_logs"

[db]
host = "127.0.0.1"
port = 5432
username = "postgres"
password = "CHANGE_ME"
database = "postgres"

[utc_offset]
hours = 2
# Can be omitted because 0 is the default.
minutes = 0

⁠Endpoints

⁠Dashboard

⁠JSON API

⁠Script

⁠Questions?

Don't hesitate to open an issue ^^