Simple Free & Open Source Hit Counter for Blogs and Websites

⭐ Features • 🏡 Self Hosting • 🖌️ Customization • 🌍 Public Instances • 📘 Documentation

⭐ Features

• Simple embeds: Generate counters easily and embed them with one <script> tag or as SVGs.
• Self hosted: Your data stays on your own server. No third party tracking, no relying on someone else's service.
• Full data ownership: Export your whole database or selected counters as JSON anytime.
• Clean control panel: Fast dashboard with search, filters, quick edits, notes, and live stats.
• Today, 7 day, 30 day stats: Clear activity views so you always know what is actually being used.
• Users, roles and API: Add users, turn permissions on or off, and use the API if you need it.
• Public or Private: Keep it public or restrict it completely.
• Abuse protection: Optional per IP limit throttle for every-visit based counters.
• Lightweight: Minimal setup, low resource usage, runs fine on small servers.
• And much more...!

So yeah... it's pretty good :)

🏡 Self Hosting

📦 Manual installation

1. Clone the project

First, download Voux and enter the project folder:

git clone https://github.com/QuintixLabs/Voux.git
cd Voux

Make sure you are running Node.js 22. If you use fnm :

fnm install 22
fnm use 22
node -v

2. Install Voux

Use one of these:

npm install                # normal install
npm install --production   # for production installs

3. Create your .env file

cp .env.example .env

Open .env and set your settings. This is where you configure your admin login, site URL, port, and other options. You must set ADMIN_USERNAME + ADMIN_PASSWORD before running the server.

If you run Voux on a public domain, set PUBLIC_BASE_URL to your full URL (for example, https://your-domain.com) so embeds and previews use the correct HTTPS address. If you want a development setup, add DEV_MODE=development. For more settings check Documentation

4. Start Voux

Development (auto-reload) :

npm run dev

Production:

npm start

By default, both commands run at: http://localhost:8787. You can change this by setting the PORT value in .env.

During development, set NODE_ENV=development in your .env to serve HTML/JS/CSS with no-store caching.

🐋 Docker

Run Voux via Docker:

docker run -d \
  --name voux \
  -p 8787:8787 \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=change-this-password \
  # -e PUBLIC_BASE_URL=https://your-domain.com \
  -v $(pwd)/data:/app/data \
  ghcr.io/quintixlabs/voux/voux:latest

Or use our docker-compose.yml, which is simpler. Just run:

docker compose up -d

• Change ADMIN_USERNAME + ADMIN_PASSWORD to your own login (do not leave it as the example).
• If deploying on a public domain, set PUBLIC_BASE_URL to your full site URL (for example, https://your-domain.com).
• Add more -e VAR=value flags for more settings if you need them.

Need more details or advanced setup options? Read the documentation.

🎨 Styling script embeds

Styling your counter with Voux is super simple. All you need to do is wrap your counter script inside an element. We'll use a <span> in this example:

<span class="counter-widget">
  <!---------------------replace this with urs--------------------->
  <script async src="https://your-domain/embed/abc123.js"></script>
</span>

Once that's in place, you can style it however you like using CSS. Here's a simple example that centers the counter on the screen and makes the text black:

.counter-widget {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  text-align: center;
  color: black;
  font-weight: 600;
  font-size: 3rem;
  font-family: system-ui, sans-serif;
}

And that's it. Your counter is now styled and ready to use. You can change the font, colors, or layout any way you like.

🧩 Styling SVGs embeds

Voux also provides an SVG embed for cases where you cannot use JavaScript, such as READMEs, Markdown files, or restricted platforms.

<img src="https://your-domain/embed/abc123.svg" alt="Voux counter">

You can also customize the SVG by passing parameters in the URL query string:

<img src="https://your-domain/embed/abc123.svg?bg=F54927&color=ffffff" alt="Voux counter">

See the documentation for a full list of SVG parameters.

👀 SVG counters on GitHub

GitHub READMEs do not allow JavaScript, so SVGs are the only option.

Mode	Info	Example
👤 Unique visitors	Not available on GitHub (images are cached and proxied, so Voux cannot use its IP-based method)	❌
🔁 Every visit	Works on refresh (try it now just refresh the page)

And on documentation websites, Unique Visitors work, check it out here!

🌐 Public instances

If you want to run your own public Voux instance and add it to the official public instances list, you can submit it here.

📄 License

Voux is Free Software: You can use, study, share and modify it at your will. The app can be redistributed and/or modified under the terms of the GNU General Public License version 3 published by the Free Software Foundation.

↥ Scroll to top