Installation

There are two ways to install Fusionaly.

• Automated Installation (recommended). One command sets up everything, including a reverse proxy.
• Self-Managed (Docker). You run the Docker image yourself and put your own reverse proxy in front of it.

Use the automated installer if you can. Use Self-Managed only if you need full control, for example a custom Docker Compose stack, or a non-Ubuntu system.

Automated Installation

This is the recommended way to install Fusionaly. It works best on Ubuntu Server.

Recommended Hosting Providers

We recommend DigitalOcean or Hetzner. Both give you reliable, affordable VPS hosting with a public IP address.

Requirements:

• A public IP address
• Ubuntu Server 20.04 or later

Important: The installer does not harden your server. You must secure the server yourself, before you install. At minimum, do this:

• Add a non-root user with SSH key login.
• Turn off password login.
• Set up a firewall.

See DigitalOcean’s Ubuntu Server Setup Guide or your provider’s equivalent guide.

The installer opens ports 80 and 443 in UFW for you.

DNS Setup

Point your domain to your server before you install. Add an A record. Add an AAAA record too if you use IPv6.

1. Install

curl -fsSL https://fusionaly.com/install | bash

The installer sets up everything for you:

• SSL certificates (Let’s Encrypt)
• A reverse proxy (Caddy)
• Automatic updates
• Daily, weekly, and monthly database backups

Cloudflare (Recommended)

We recommend Cloudflare in proxied mode (orange cloud icon). Cloudflare blocks bots and attacks before they reach your server. This keeps your analytics data clean. It also reduces load on your server.

Setup:

1. Add your domain to Cloudflare. The free plan works.
2. Point the DNS A record to your server IP.
3. Turn on the proxy toggle (orange cloud).
4. Set SSL mode to Full (strict).

---

Self-Managed (Docker)

Use the automated installer above if you can. It already includes a reverse proxy, SSL, and backups.

Use this section if you want to assemble the pieces yourself. For example, run the Docker image and put your own reverse proxy (nginx, Traefik, or Caddy) in front of it. This path gives you full control, but you handle the reverse proxy, updates, and backups yourself.

The Docker image is karloscodes/fusionaly. It supports AMD64 and ARM64. Use the latest tag.

Quick Start

docker run -d \
  --name fusionaly \
  -p 8080:8080 \
  -e FUSIONALY_DOMAIN="your-domain.com" \
  -e FUSIONALY_PRIVATE_KEY="$(openssl rand -hex 32)" \
  -v fusionaly-storage:/app/storage \
  -v fusionaly-logs:/app/logs \
  karloscodes/fusionaly:latest

This starts Fusionaly on port 8080. It is not reachable from the internet yet. See Put a Reverse Proxy in Front below.

Environment Variables

Variable	Required	Description
FUSIONALY_DOMAIN	Yes	Your domain name
FUSIONALY_PRIVATE_KEY	Yes	Encryption key (openssl rand -hex 32)
FUSIONALY_LOG_LEVEL	No	debug, info, warn, error (default: info)

Data Persistence

Mount two volumes: /app/storage for the database, and /app/logs for log files.

Put a Reverse Proxy in Front (Example: nginx)

Fusionaly reads the X-Forwarded-Host and X-Forwarded-Proto headers from each request. It uses them to build the tracking URL. If your reverse proxy does not send these headers, the tracking script uses the wrong host. This is often the internal Docker address, not your public domain.

Here is an nginx example. Set these headers in your proxy_pass block:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

By default, nginx does not forward the original Host header. Without proxy_set_header Host $host;, nginx sends the upstream address instead, for example 127.0.0.1:8080.

Caddy and Traefik forward these headers by default. You do not need extra config for them.

Still wrong after you fix your proxy? The SDK response is cached for one hour. Wait one hour, or clear your browser cache for /y/api/v1/sdk.js.

Escape hatch: you can set the host directly on your page. This works with no proxy config. See host in SDK Configuration.

<script>
  window.Fusionaly = window.Fusionaly || {};
  window.Fusionaly.config = { host: "https://your-domain.com" };
</script>
<script defer src="https://your-domain.com/y/api/v1/sdk.js"></script>

Updating

docker pull karloscodes/fusionaly:latest
docker stop fusionaly && docker rm fusionaly
# Re-run with the same FUSIONALY_PRIVATE_KEY

Note: Self-managed setups do not include automatic updates or backups. You must set these up yourself.