Installation

Get RAT up and running on your machine in under 5 minutes. No git clone needed — just Docker.

Prerequisites

Before installing RAT, make sure you have the following installed:

Requirement	Minimum Version	Check Command
Docker	24.0+	`docker --version`
Docker Compose	2.20+ (V2 plugin)	`docker compose version`
RAM	4 GB free	—
Disk	2 GB free	—

⚠️

RAT runs 7 containers simultaneously. If your machine has less than 4 GB of free RAM, you may experience slow startups or container crashes — especially the runner and ratq services which load DuckDB and PyArrow into memory.

Docker Compose V2 is required (the docker compose plugin, not the legacy docker-compose standalone binary). Most modern Docker Desktop installations include V2 by default.

Quick Install

Run a single command to download everything and start RAT:

Terminal

curl -fsSL https://raw.githubusercontent.com/squat-collective/rat/main/install/install.sh | bash -s -- --start

This creates a rat/ directory with docker-compose.yml and .env, then starts all services. Once complete, open http://localhost:3000.

Manual Install

If you prefer to do things step by step:

Create a directory and download files

Terminal

mkdir rat && cd rat
curl -fsSL https://raw.githubusercontent.com/squat-collective/rat/main/install/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/squat-collective/rat/main/install/.env -o .env

Start all services

Terminal

docker compose up -d

The -d flag runs containers in detached mode so you get your terminal back.

The first start takes 2-5 minutes because Docker needs to pull all images. Subsequent starts are much faster thanks to layer caching.

Wait for health checks

All services register health checks with Docker. Wait until every container reports healthy:

Terminal

docker compose ps

You should see output similar to:

NAME          STATUS                  PORTS
postgres      Up 30s (healthy)        5432/tcp
minio         Up 30s (healthy)        9000/tcp, 9001/tcp
nessie        Up 30s (healthy)        19120/tcp
ratd          Up 25s (healthy)        0.0.0.0:8080->8080/tcp
runner        Up 20s (healthy)
ratq          Up 20s (healthy)
portal        Up 15s (healthy)        0.0.0.0:3000->3000/tcp

The minio-init container will show status Exited (0) — this is normal. It runs once to create the S3 bucket and enable versioning, then exits.

You can also verify individual services manually:

Terminal

# Check the API server
curl -s http://localhost:8080/health | jq .
 
# Check the portal
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

Open the Portal

Once all services are healthy, open your browser and navigate to:

http://localhost:3000

You should see the RAT Portal dashboard. No login is required for the Community Edition — it is a single-user platform.

Pinning a Version

By default, the install uses the latest tag. To pin a specific release:

Terminal

# During install
curl -fsSL https://raw.githubusercontent.com/squat-collective/rat/main/install/install.sh | bash -s -- --version=2.1.0
 
# Or manually — replace :latest with the version tag in docker-compose.yml
# image: ghcr.io/squat-collective/ratd:2.1.0

Pinning a version is recommended for production to avoid unexpected changes. Check the releases page for available versions.

Service Ports

These are the ports exposed on your host machine:

Service	Port	URL	Description
Portal	3000	localhost:3000	Web IDE — your main interface
API (ratd)	8080	localhost:8080	REST API server
MinIO Console	9001	localhost:9001	S3 storage admin UI
Nessie	19120	localhost:19120	Iceberg catalog API

The runner and ratq services do not expose ports to the host — they communicate with ratd over the internal Docker network via gRPC.

Default Credentials

Service	Username	Password	Configured In
MinIO Console	`minioadmin`	`minioadmin`	`.env` → `S3_ACCESS_KEY` / `S3_SECRET_KEY`
PostgreSQL	`rat`	`rat`	`.env` → `POSTGRES_USER` / `POSTGRES_PASSWORD`

The MinIO console at localhost:9001 lets you browse the raw data files stored in S3. You do not need to access it during normal use — it is helpful for debugging and verifying that pipeline data has been written correctly.

⚠️

These are development credentials. If you deploy RAT in production, change them in your .env file. See the Deployment section for guidance.

Stopping RAT

To stop all services while preserving your data:

Terminal

docker compose down

To stop all services and delete all data (volumes):

Terminal

docker compose down -v

🚫

The -v flag removes all Docker volumes, which means all your pipelines, runs, tables, and stored data will be permanently deleted. Use this only when you want a clean slate.

Upgrading

Pull the latest images and restart:

Terminal

docker compose pull
docker compose up -d

If you pinned a version, update the tags in docker-compose.yml first (or re-run the installer with --version=X.Y.Z).

See the full Upgrading guide for backup procedures, rollback, and migration details.

Troubleshooting

Port conflicts

If a port is already in use, Docker will fail to bind it. Check for conflicts:

Terminal

# Check which process is using port 3000
lsof -i :3000
 
# Or on Linux without lsof
ss -tlnp | grep 3000

Common conflicts:

Port 3000 — Another Node.js or React development server
Port 8080 — Java application servers, other API servers
Port 9001 — Other MinIO instances
Port 5432 — A local PostgreSQL installation

To resolve, either stop the conflicting process or override the port in your compose environment.

Container crashes or OOM

If containers keep restarting, you likely do not have enough memory:

Terminal

# Check container resource usage
docker stats --no-stream

Solutions:

Close other memory-intensive applications (browsers, IDEs)
Increase Docker Desktop memory limit (Settings -> Resources -> Memory -> set to 4 GB+)
On Linux with cgroup limits, ensure the Docker daemon has at least 4 GB available

Checking logs

View logs for all services:

Terminal

docker compose logs -f

View logs for a specific service:

Terminal

# API server logs
docker compose logs -f ratd
 
# Runner logs (pipeline execution)
docker compose logs -f runner
 
# Portal logs
docker compose logs -f portal

Services fail to connect to each other

If ratd reports that it cannot reach runner, ratq, or Nessie, the services may have started out of order. Restart them:

Terminal

docker compose restart ratd runner ratq

Clean start

If something is fundamentally broken, you can start completely fresh:

Terminal

docker compose down -v
docker compose pull
docker compose up -d

Developer Setup

Want to build from source, run tests, or contribute? See the Contributing guide which covers cloning the repo, make targets, and the full development workflow.

Next Steps

Build a data pipeline from scratch in 10 minutes

Your First Pipeline

Explore the web IDE and all its features

Portal Tour

Core Concepts