# Installation

- [Meet NiceTryBot](#meet-nicetrybot)
    - [Why NiceTryBot?](#why-nicetrybot)
- [Installing NiceTryBot](#installing-nicetrybot)
    - [Getting Started Using AI](#getting-started-using-ai)
    - [Server Requirements](#server-requirements)
    - [Running the Installer](#running-the-installer)
    - [Unattended Installation](#unattended-installation)
- [What Gets Installed](#what-gets-installed)
- [Initial Configuration](#initial-configuration)
    - [Environment Based Configuration](#environment-based-configuration)
    - [Managed Postgres and Valkey](#managed-postgres-and-valkey)
    - [Teams and Registration](#teams-and-registration)
- [Installing With Docker Compose](#installing-with-docker-compose)
- [The NiceTryBot CLI](#the-nicetrybot-cli)
- [Next Steps](#next-steps)

## 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](https://caddyserver.com) 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](https://docs.nicetrybot.com/docs/0.x/mcp.md), 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](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://developers.openai.com/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:

```text
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:

<div class="content-list" markdown="1">

- 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.

</div>

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:

```shell
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:

<div class="content-list" markdown="1">

- 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`.

</div>

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](https://docs.nicetrybot.com/docs/0.x/upgrade.md).

### 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:

```shell
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](https://docs.nicetrybot.com/docs/0.x/addons.md) 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:

```shell
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:

<div class="content-list" markdown="1">

- **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.

</div>

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:

```shell
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:

```shell
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:

```shell
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](https://docs.nicetrybot.com/docs/0.x/cli.md) 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:

<div class="content-list" markdown="1">

- [Adding Domains](https://docs.nicetrybot.com/docs/0.x/domains.md)
- [Protecting Your Origins](https://docs.nicetrybot.com/docs/0.x/origins.md)
- [Core Concepts](https://docs.nicetrybot.com/docs/0.x/concepts.md)

</div>