How to Self-Host Holy Unblocker: Complete Beginner's Guide

Holy Unblocker is an open-source, browser-based web proxy project. Some people prefer running their own instance to relying on a public one, and that is what self-hosting means: installing and running the software on a server you control. It involves getting a server, installing the required software, configuring the project, connecting a domain and maintaining the install.

What Self-Hosting Involves

• VPS: a virtual private server that runs the application.
• Linux: the operating system you manage it with.
• Node.js and a package manager: the runtime and dependency installer.
• Nginx: a web server and reverse proxy in front of the app.
• Domain and HTTPS: the address visitors use, and encryption for their connections.

For example, you buy a VPS, point proxy.example.com at it, run the app locally and let Nginx handle incoming requests. Exact steps depend on the project version and its deployment instructions. For how the pieces work together at runtime, see how Holy Unblocker works.

Why Self-Host?

• Control over configuration: updates, resources, domain settings, and direct access to logs when something breaks.
• Control over hosting: you choose the provider and who has admin access. That isn't complete privacy, since the provider can still see infrastructure-level information and the app may log.
• A custom domain: such as proxy.example.com, but you must own or control the domain.
• Learning: Linux, DNS, reverse proxies, HTTPS and deployment skills that carry over to other projects.

Requirements

VPS and operating system

A VPS gives you control of the OS and the app process. Check the provider's acceptable-use policy first, because some restrict public web proxies. A small test deployment may need modest resources, but needs grow with visitors, traffic and version, so watch CPU, RAM, bandwidth, storage and connection limits. A current Ubuntu LTS or another Linux distribution supported by the docs is a good start. The commands below use Ubuntu/Debian package management.

Node.js and package manager

The runtime must match your chosen version. Older Holy Unblocker and newer InvisiProxy instructions may differ, and the InvisiProxy README has listed Node.js 20.x in one place while showing newer setup elsewhere. Follow the exact runtime requirement for your selected branch and commit. The project currently documents pnpm.

Git, Nginx, a domain and basic skills

Git downloads the source. Nginx receives public traffic and forwards it to the app, and the README warns about reverse-proxy configuration involving Wisp-related loopback behavior, so read its Nginx instructions before exposing anything. A domain is optional for local tests but useful publicly. You should be comfortable with SSH, running commands, editing config files and reading errors. If you are new to Linux, practice on a test server first.

Step 1: Prepare Your VPS

Get the server's public IP and SSH credentials from your host, then connect:

ssh your_username@YOUR_SERVER_IP

Update the system and install Git, curl and Nginx:

sudo apt update
sudo apt upgrade
sudo apt install git curl nginx
sudo systemctl status nginx
sudo systemctl enable --now nginx    # only if it isn't running

Don't expose an unfinished app to the public internet before reviewing its configuration and security.

Step 2: Install Node.js and pnpm

The docs describe Node Version Manager (NVM) as one way to manage versions. Install it from github.com/nvm-sh/nvm, open a new session, then install the version your branch requires (Node 20 shown as an example):

nvm install 20
nvm use 20
node -v
npm -v

Don't pick a runtime just because it is newer, since dependencies can behave differently across major releases. For pnpm, check whether Corepack is included and follow the project's documented setup:

corepack --version
pnpm --version

If pnpm isn't recognized, fix that before continuing, and keep the project's lockfile intact for reproducible installs.

Step 3: Download the Project

Decide whether you need historical Holy Unblocker code or the current continuation. For a new deployment, use the official InvisiProxy repository:

git clone https://github.com/QuiteAFancyEmerald/InvisiProxy.git
cd InvisiProxy

Read the README and branch information first. The repository separates development code from deployment-oriented branches and warns that the main development branch can contain work-in-progress changes, so pick an appropriate production branch for self-hosting rather than assuming the newest is the most stable.

Step 4: Install Dependencies and Start

The repository currently documents this general sequence, but follow your branch's README if it differs:

pnpm run fresh-install
pnpm run fetch-adblock
pnpm start

The first prepares the project and dependencies, the second fetches ad-blocking resources, and pnpm start launches the app. Review scripts before running them, since they execute code on your server. Port 8080 is documented as the default, though it can vary by configuration and branch. For first tests, reach it from the server itself or via an SSH tunnel, and don't expose the app port publicly unless you've deliberately secured it. A test command, pnpm run test, is also documented.

If installation fails, common causes are an unsupported Node.js version, missing system dependencies, insufficient memory, network problems or a package-manager mismatch. Read the terminal output before trying random commands.

Step 5: Configure the Application

The documentation identifies config.json and ecosystem.config.js as relevant configuration files, though options change between releases, so check the current README. Settings can cover the port, production mode, caching, logging, proxy engines and transports (see Holy Unblocker features).

• Port: if you change it, make the app and Nginx configs agree.
• Production settings: read each option's description for your version, and don't enable one just because a tutorial says so.
• Secrets: never commit credentials or keys to a public repository. Use environment variables or protected files and restrict permissions.
• Exposure: don't expose admin interfaces or development endpoints publicly.

Step 6: Configure Nginx

Nginx sits between visitors and the app: Visitor → HTTPS → Nginx → local application. The exact config depends on the version, required WebSocket or Wisp-related connections, domain and TLS setup, so use the repository's current deployment guidance rather than a generic template. A typical setup includes a server block for your domain, the right app address and port, header forwarding, HTTPS, correct handling of upgraded connections, and restricted access to private endpoints.

Validate before reloading:

sudo nginx -t
sudo systemctl reload nginx

If validation fails, fix the configuration first.

Step 7: Connect Your Domain and Enable HTTPS

Add DNS records pointing at your server. For a subdomain:

Visitors would then use https://proxy.example.com (replace with a domain you own). Follow your DNS provider's current instructions, such as Cloudflare's, and allow time for propagation.

For a public deployment, get a valid TLS certificate, for example from Let's Encrypt, following its current instructions for Nginx. Afterwards check that:

• The certificate matches your domain and hasn't expired.
• HTTP redirects to HTTPS where intended.
• The reverse proxy is configured correctly.
• The app doesn't expose private ports unnecessarily.

If you use a DNS proxy service, understand its TLS mode and don't pick one that leaves the origin connection unprotected. HTTPS doesn't guarantee the app itself is free of vulnerabilities.

Step 8: Keep It Running

An app started in a terminal can stop when your session ends. For long-running deployments, use the process method your version supports. The InvisiProxy docs describe production configuration with PM2 and project-provided scripts, and document commands such as:

pnpm restart
pnpm run kill

Use them only as described for your version, and don't start multiple competing copies. Afterwards, confirm the app comes back after a server reboot.

Step 9: Test Before Sharing

• Application: starts without fatal errors and responds on its local port.
• Domain and HTTPS: resolves to your server with a valid certificate.
• Proxy function: try a few ordinary sites. A successful install doesn't mean every site works.
• Logs: review app and Nginx logs for repeated errors or odd traffic.
• Resources: watch CPU, RAM, bandwidth and storage under use.

A homepage that loads isn't proof the deployment is production-ready.

Common Problems

• Install fails: unsupported Node.js, missing pnpm, a failed download or different branch requirements. Check the output and rerun the documented commands.
• App won't start: confirm dependencies installed and the port is free. Resolve conflicts instead of launching duplicates.
• Domain won't open: check DNS records, server IP, firewall, Nginx config, TLS certificate, and that the app is listening locally.
• Nginx 502: Nginx can't reach the app. Check it is running, the upstream address and port are right, and read the Nginx error log.
• Some sites don't work: JavaScript, authentication, CAPTCHA and WebSockets can break through a proxy. Check whether it's one site or the whole deployment (see common problems and fixes).
• Server is slow: high CPU, low RAM, limited bandwidth or heavy traffic. Monitor before upgrading.
• Stops when SSH closes: use the supported production process manager and verify it survives logout and reboot.

Security Best Practices

A self-hosted proxy needs ongoing administration. It isn't set-and-forget.

1. Update the OS and install security patches regularly.
2. Use a supported project version, not an abandoned or experimental branch.
3. Restrict access: SSH keys where possible, and no unnecessary open ports.
4. Use HTTPS and keep certificates valid.
5. Review dependencies and watch project updates and advisories.
6. Protect logs and config files and avoid storing unnecessary sensitive data.
7. Monitor resources for unexpected traffic and errors.
8. Back up configuration and test restoring it.
9. Respect hosting policies for your intended use.
10. Understand privacy limits. Self-hosting gives more control but doesn't guarantee anonymity (see our disclaimer).

If other people use your instance, your responsibility grows: think about abuse prevention, resource limits, monitoring and the legal requirements for your location and users.

Cost and Hosting Options

The software may be free, but a public instance can cost money for VPS hosting, domain registration, backups, extra bandwidth, monitoring and your time. Free tiers often limit bandwidth, runtime, public services or acceptable use, so read the terms before relying on one. Traditional shared hosting usually doesn't allow persistent Node.js apps or the needed network behavior, so a VPS or compatible app-hosting environment is generally more practical. Verify that the provider supports the runtime, long-running processes, reverse-proxy needs and your intended use. The homepage self-host section has the short version.

Frequently Asked Questions

Conclusion

Self-hosting gives you more control over the server, configuration and domain behind your browser-based proxy. The process is: prepare a compatible VPS, install the required runtime and dependencies, download the right project branch, configure the app, set up Nginx and HTTPS, connect DNS and test.

Related Guides