Installation

Meet NiceTryBot

NiceTryBot is a batteries-included, bot-fighting framework for all of your websites. It places an edge in front of your sites that sees every request, gives you rules you can read out loud, and sends the bots you choose to a gym where they can burn off some energy. Your real visitors never notice a thing.

NiceTryBot runs on your own servers. There is no hosted service to sign up for and no account is needed to run it. Your traffic, your rules, and your visitors' data stay on infrastructure you control.

Why NiceTryBot?

There are plenty of ways to put a wall in front of a website. NiceTryBot takes a different approach: it watches first, explains what it sees, and only acts when you decide it should.

An Edge That Sees Everything

Every request passes through NiceTryBot's edge, a build of Caddy that terminates TLS for your domains. Because the edge reads each visitor's own TLS handshake, it can fingerprint the software that connected, not just the user agent it claims to be. A script pretending to be Chrome has a very hard time hiding.

Rules You Can Read Out Loud

Rules are written in a small language that reads like SQL. Before a rule ever runs, NiceTryBot tests it against your real traffic so you can see exactly who it would have caught:

Rule

-- Anyone fishing for secrets, admin panels or exploits.
BAN ip, ja4 FOR 30 DAYS
WHERE category = 'probe'

A Gym, Not a Wall

Instead of simply blocking a suspicious visitor, NiceTryBot can send it through the bot gym: a series of obstacles that cost a bot CPU time and patience but only cost a person a moment. Bots get a workout. People get to their page.

An Agent Ready Product

Every page of this documentation is available as plain Markdown, NiceTryBot's control panel ships with an MCP server, and most setup tasks come with a prompt you can paste straight into Claude Code, Codex, or Cursor. If you would rather have an agent do the typing, you are in good company.

Installing NiceTryBot

Getting Started Using AI

If you are using an AI coding agent like Claude Code or Codex, you can hand it the installation entirely. The prompt below points your agent at NiceTryBot's deployment brief and these docs, then asks it to check its plan with you before it changes anything. Paste this into your agent to get started:

I'd like to install NiceTryBot on a server I control.

Fetch and follow https://nicetrybot.com/deploy/agent.md, and use https://docs.nicetrybot.com/llms.txt for anything else you need to know. Treat both as the source of truth. Check the server and the DNS records with me before you change them.

The agent should walk you through choosing a server, pointing your panel's hostname at it, and running the installer described below.

Server Requirements

NiceTryBot runs as a small set of Docker containers on a single Linux server. Before installing, make sure you have:

A fresh server running Ubuntu 24.04 LTS or a recent Debian release. Intel and ARM servers both work.
At least 2 vCPU, 4 GB of RAM, and 40 GB of disk for production use. A 1 vCPU, 2 GB server is enough for a trial.
Ports 80 and 443 open to the world. Nothing else needs to be public.
A hostname for the control panel, such as panel.example.com, with an A record pointing at the server.
Access to the DNS for every site you plan to protect.

The installer will install Docker Engine 27 or newer and the Compose plugin for you if they are missing.

Warning

Nothing may terminate TLS in front of the edge. The edge fingerprints each visitor's own TLS handshake, so a load balancer in front of it must pass raw TCP: an AWS Network Load Balancer with TCP listeners, a DigitalOcean load balancer in TCP passthrough mode, or HAProxy in mode tcp. Application load balancers, CloudFront, nginx, and Cloudflare's orange-cloud proxy all terminate TLS and should not sit in front of NiceTryBot.

Running the Installer

Once your panel's hostname points at the server, SSH into it and run the installer:

Terminal

curl -fsSL https://nicetrybot.com/install.sh | sudo bash

The installer will ask for three things: your control panel's hostname, an email address for Let's Encrypt certificate notices, and the email address of your first administrator. It then:

Installs Docker, if needed.
Writes the stack to /opt/nicetrybot, including a compose.yml file and an .env file with freshly generated secrets.
Pulls the images, starts the stack, and creates your first administrator.
Prints the DNS records your protected sites will need.
Installs the nicetrybot command at /usr/local/bin/nicetrybot.

When the installer finishes, it prints your administrator's password exactly once. Copy it somewhere safe, then visit https://panel.example.com and sign in.

Note

Running the installer again on a server where NiceTryBot is already running is perfectly safe. It hands over to nicetrybot update, which is described in the upgrade guide.

Unattended Installation

When provisioning servers with cloud-init or another automation tool, you may pass every answer to the installer as an option and skip the questions entirely:

Terminal

curl -fsSL https://nicetrybot.com/install.sh | sudo bash -s -- --unattended \
  --panel-host=panel.example.com \
  --acme-email=you@example.com \
  --admin-email=you@example.com

The installer accepts the following options:

Option	Description
`--dir=PATH`	Where the stack lives. Defaults to `/opt/nicetrybot`.
`--version=VERSION`	The release to run, such as `0.1.0`. Defaults to the latest release.
`--compose-only`	Only write `./nicetrybot/compose.yml` and `./nicetrybot/.env`, then stop.
`--unattended`	Ask nothing. Requires `--panel-host` and `--acme-email`.
`--panel-host=HOST`	The control panel's hostname.
`--acme-email=EMAIL`	Where Let's Encrypt sends certificate notices.
`--admin-email=EMAIL`	The first administrator. Defaults to the ACME email when unattended.
`--admin-password=PASS`	Their password. Defaults to a random password, shown once.
`--addons=LIST`	Marketplace add-ons to build in, or `all`.
`--composer-token=TOKEN`	The Composer token from your account on nicetrybot.com.

What Gets Installed

A NiceTryBot installation is a Docker Compose stack. Each service has one job:

Service	Description
`edge`	Caddy with NiceTryBot's modules. Terminates TLS, fingerprints visitors, applies rules, and runs the gym. Serves the control panel and every verified domain, issuing certificates on demand.
`vector`	Tails the edge's access log, adds location data, redacts sensitive values, and ships each line to the app.
`app`	The control panel and the edge's API. Runs database migrations every time it starts.
`worker`	Processes the queue.
`scheduler`	Runs scheduled tasks, such as evaluating your rules every minute.
`postgres`	The database. NiceTryBot uses Postgres 17 in production.
`valkey`	Cache, queue, sessions, and locks.

Nothing in the stack calls home. The only outbound requests NiceTryBot makes are for TLS certificates, the monthly DB-IP Lite location databases, pulling images, a daily check for new releases, and, if you have entered a paid add-on's licence key, a daily check that the key is still valid. You may disable the release check by setting NICETRY_UPDATE_CHECK=false.

Initial Configuration

Environment Based Configuration

NiceTryBot's settings live in the .env file beside compose.yml, which is /opt/nicetrybot/.env by default. The installer fills it in for you, and every key is described in the file itself. A few you are likely to reach for:

Key	Description
`NICETRY_PANEL_HOST`	The control panel's hostname.
`NICETRY_EDGE_HOSTNAME`	The `CNAME` target the Domains page tells people to use. Defaults to the panel host.
`NICETRY_EDGE_ADDRESSES`	The IPv4 addresses `A` records should point at, separated by commas.
`NICETRY_REGISTRATION`	Who may create an account: `invitations` (the default), `open`, or `closed`.
`NICETRY_PREVIEW_ZONE`	A wildcard zone for preview hostnames. Previews are off when this is empty.
`NICETRY_VERSION`	The release to run, such as `0.1.0`, or `latest`.
`NICETRY_UPDATE_CHECK`	Set to `false` to turn off the daily release check.

After editing the .env file, apply your changes by restarting the stack:

Terminal

nicetrybot apply

Warning

The installer generated APP_KEY, NICETRY_EDGE_TOKEN, and your database passwords. Keep a backup of your .env file somewhere safe, and never commit it to source control.

Managed Postgres and Valkey

By default, NiceTryBot runs Postgres and Valkey alongside the rest of the stack. If you would rather use a managed database or cache, remove the matching profile from COMPOSE_PROFILES and point the usual DB_* and REDIS_* keys at your managed service. The bottom of the .env file includes ready-made presets for DigitalOcean and AWS.

You may also run NiceTryBot without Redis at all. Set CACHE_STORE, QUEUE_CONNECTION, and SESSION_DRIVER to database and set COMPOSE_PROFILES=postgres.

Teams and Registration

Everything in the control panel belongs to a team. Your first administrator gets a personal team automatically, and you may invite teammates from Settings → Teams. Each member has one of three roles:

Owner may do everything.
Admin may update the team, invite members, and manage domains, rules, the gym, and visitor data.
Member has read-only access.

Administrators are a separate, installation-wide role. They see the Admin pages for add-ons, administrators, and API tokens. To make another user an administrator, run:

Terminal

nicetrybot artisan admin:grant you@example.com

Installing With Docker Compose

If you would rather manage Docker yourself, the installer can write the stack's files and stop there. You may then start the stack and create your first administrator by hand:

Terminal

curl -fsSL https://nicetrybot.com/install.sh | bash -s -- --compose-only

cd nicetrybot
docker compose up -d
docker compose exec app php artisan nicetry:install

The nicetry:install command creates your first administrator, prints the password once, and prints the DNS records your sites will need. Running it again when an administrator already exists changes nothing.

Note

Docker is the supported way to run NiceTryBot. The control panel is a standard Laravel application and can run on a plain PHP host, but the edge cannot sit behind nginx and always needs a server of its own.

The NiceTryBot CLI

The installer adds a nicetrybot command to your server. It wraps the Docker commands you would otherwise type by hand:

Terminal

nicetrybot status           # The release, the containers, and the add-ons
nicetrybot doctor           # Check the server, containers, panel and app, with advice
nicetrybot logs edge        # Follow a service's logs
nicetrybot apply            # Restart the stack with what you changed in .env
nicetrybot artisan about    # Run an Artisan command in the app

If something doesn't look right, nicetrybot doctor is the best place to start. It is also a great command to let your agent run, since its output explains what it found.

The same command can add domains and work with the rest of the control panel, on the server or from your laptop. See NiceTryBot CLI for everything it does.

Next Steps

Now that NiceTryBot is running, you are ready to put your first site behind it. We recommend reading the following documentation next: