---
name: tapitalee
description: Manage and deploy containerized apps on Tapitalee (ECS Fargate on the user's AWS account) using the tapit CLI. Use for deploying apps, managing processes, add-ons, variables, domains, commands, tasks, and logs.
---

# Tapitalee

Tapitalee is a SaaS that deploys containerized apps to the customer's own AWS account using ECS Fargate. It provisions ECR, ECS services/task definitions, VPCs, and triggers deploys with sensible defaults including blue/green deployments (new containers start before old ones stop).

## Your primary tool: the `tapit` CLI

**Always use the `tapit` CLI to interact with Tapitalee.** It is the tool of choice for all inspection and management operations.

### Getting started (run these first)

```sh
tapit ping                          # confirm authentication (attempts login if not)
tapit list teams                    # discover team names
tapit -t TEAM -a APP show summary   # THE key command: full app overview to work from
```

`show summary` gives you everything you need to proceed working on an app: its processes, add-ons, variables, domains, commands, deploy status, and more.

### Targeting: team and app

Almost every command must be directed at a team and app:

```sh
tapit -t TeamName -a AppName <command> <resource> [option=val ...]
```

- `-t TeamName` is required on every command (see `tapit list teams`).
- `-a AppName` is required for most commands.
- The environment variables `TAPIT_TEAM` and `TAPIT_APP` may already be set by the user; if so, the flags can be omitted.

### Self-documentation

```sh
tapit help                    # Compact list of every CLI command
tapit help <command>          # Full usage for a specific command
tapit help apireference       # dump full CLI/API reference (YAML)
tapit help docs               # Compact list documentation topics
tapit help docs <topic>       # output the doc as Markdown
```

Use `help apireference` when unsure of a command, resource, or option. Use `help docs` for how-to guides.

## Tapitalee structure

An **App** belongs to a **Team** and is deployed to one AWS region (in a VPC). It consists of:

| Resource | Description |
|---|---|
| **Processes** | Long-running containerized services (ECS Fargate Services). The `default` process is externally accessible (e.g. webserver) with a port, hostname, allowed IP ranges. Each has cpu/memory, demand/spot counts, optional autoscaling, optional custom image, and can be deployed/stopped/started/restarted individually. |
| **Add-ons** | Managed services deployed alongside the app: RDS databases, Redis, S3, EFS, EC2 instances, TLS proxies (Traefik with ACME certs), Datadog, etc. They inject connection details as env vars and auto-configure IAM policies / security-group rules. Can be shared with other apps in the same team+region. Changing add-ons redeploys the app. |
| **Variables** | Environment variables (user-defined or add-on-supplied). Secrets are stored in AWS Secrets Manager. Setting one redeploys the app. |
| **Domains** | Custom domains routed via proxy add-ons. Users should CNAME to the app's `internal_full_hostname`. Changing domains redeploys the app. |
| **Commands** | Short-running on-demand tasks (one-off ECS tasks), optionally on a cron-like schedule, or used as predeploy steps. |
| **Predeploy steps** | Commands run in order before each deploy completes (migrations, asset compilation). A failure aborts the deploy; the app stays on the previous version. |
| **Deploys/Releases/Tasks** | Deployment history and one-off task runs. |

Users have roles: `read_only` < `member` (deploy, variables, domains, tasks, consoles) < `admin` (everything on apps) < `owner` (memberships, billing), plus granular access rights.

## Common workflows

- **Deploy**: `tapit image deploy` handles everything in one step. Check with `tapit show deploy` or `tapit list deploys`.
- **Run a one-off command**: `tapit create task` (background; view with `tapit list tasks`, logs with `tapit show logs task=NAME`).
- **Interactive console**: `tapit run bash` (foreground terminal in a fresh ephemeral container — the app image needs bash and curl). Tasks never attach to running containers; each spins up a fresh container.
- **Logs**: `tapit show logs` (add `task=NAME` for task logs).

## Agent guidance

- Start every session with `tapit ping`, `tapit help apireference`, and then `tapit -t TEAM -a APP show summary`.
- States for apps/processes/add-ons: `provisioning`, `modifying`, `deleting` (plus `pending`/`failed` variants). `active` means idle/provisioned.
- Don't assume full visibility: application-layer or deployment-level issues may not be visible to Tapitalee. Ask the user for details when needed.
- For deeper reference: `tapit help docs` for index then `tapit help docs <topic>` for details.