carousell-monitor/docs/QUICKSTART-PORTAINER.md

Quick start on Portainer (click-by-click)

For a fresh machine, no shell needed. Portainer runs the same compose file as the CLI flow — see the README for that version.

Before you start: Portainer must already be up and connected to a Docker endpoint, and its container needs access to the Docker socket (the standard install does). NocoDB needs one free host port — 8080 by default.

One thing to know up front: the monitor's image is built from this repository (build: .). Portainer's Web editor and Upload options have no build context, so they cannot build it:

compose build operation failed: failed to solve: failed to read dockerfile:
open /volume1/@docker/tmp/buildkit-mount…/Dockerfile: no such file or directory

That leaves two routes. Route 1 needs no shell.

---

Route 1 — deploy from the Git repository (recommended)

1. Stacks → Add stack

2. Name: carousell-monitor

3. Build method: Repository

4. Repository URL: https://github.com/hoelee/carousell-monitor Reference: refs/heads/main Compose path: docker-compose.allinone.yml

5. Environment variables — add:

   Variable	Value
   NC_AUTH_JWT_SECRET	output of openssl rand -hex 32
   TELEGRAM_BOT_TOKEN	from @BotFather
   TELEGRAM_CHAT_ID	from @userinfobot
   NOCODB_PORT	optional, default 8080

   Add NOCODB_TOKEN and NOCODB_BASE_ID too if you already have them (e.g. you are reusing an existing NocoDB). On a fresh install you cannot: they do not exist yet. Leave them empty.

6. Deploy the stack. carousell-nocodb comes up healthy. carousell-monitor will restart in a short loop logging NOCODB_TOKEN not set — expected, it needs the values from step 8. Stop that container for now if you prefer a clean list.

2. Create the base and collect the two values

Open http://<your-host>:8080:

1. Create the admin account.
2. Create a base (+ New Base) — call it Carousell.
3. Copy the base id from the URL (…/nc/base/<BASE_ID>/…).
4. Avatar (bottom-left) → Account Settings → Tokens → Create token, copy the nc_pat_… value. It is shown once.
5. Do not create tables by hand — the monitor does that on start.

3. Hand the values to the monitor

1. Stacks → carousell-monitor → Editor (or Environment variables).

2. Fill in NOCODB_BASE_ID and NOCODB_TOKEN, then Update the stack.

3. Portainer recreates the monitor. Containers → carousell-monitor → Logs should now end with one line:

   ready: listings=… settings=… ignored_sellers=… ignored_keywords=… seen=0
   

   and the container status should be healthy within a couple of minutes.

   ⚠️ Portainer masks secret-looking values typed into its environment panel and stores the mask (***) with the stack — on a later stack update the container receives *** and authentication silently fails. If that happens, put the real values directly in the YAML in the Editor tab instead of the panel.

4. Start using it

In NocoDB, open the base — four tables now exist (Listings, Settings, IgnoredSellers, IgnoredKeywords). Add your first watch to Settings (details), give it a minute, then untick notified on any Listings row to force a test alert into Telegram.

---

Route 2 — Web editor, with the image built by hand first

Use this when Portainer cannot reach your Git host, or you want a self-contained stack file.

# on the Docker host (or anywhere with access to its daemon)
git clone https://github.com/hoelee/carousell-monitor.git
cd carousell-monitor
docker build -t carousell-monitor:latest .

Then:

1. Stacks → Add stack → Web editor, name it carousell-monitor.
2. Paste docker-compose.allinone.yml and remove the build: . line from the carousell-monitor service — a build: entry in a web-editor stack can only fail (no Dockerfile in Portainer's stack directory).
3. Fill in NC_AUTH_JWT_SECRET, NOCODB_PORT, and the Telegram values. Deploy, then follow §2 and §3 above to add the base id and token.

Updating the code later:

git pull && docker build -t carousell-monitor:latest .

then Update the stack in Portainer.

---

Everyday maintenance in Portainer

Task	Where
Change a search / filter	NocoDB UI — nothing to redeploy
Change credentials or tuning	Stacks → carousell-monitor → Editor → Update the stack
Deploy a code change	Route 1: Update the stack (Portainer re-clones). Route 2: git pull && docker build …, then Update the stack
See why it is unhealthy	Containers → carousell-monitor → Logs, then Listings / Settings in NocoDB for the real progress
Restart	Containers → carousell-monitor → Restart — state is in NocoDB, nothing is lost
Back up	Volumes → nocodb-data (all data), or NocoDB's own base export
Upgrade NocoDB	edit the image tag in the Editor → Update the stack; back the volume up first

Notes and limits

• A Repository stack re-clones the repo on every deploy, so the update is always a full fetch of main. That is fine here (the repo is small) and it means you get fixes by pressing one button.
• Portainer deploys standalone compose stacks for this — no Swarm involved.
• GitOps updates (auto-redeploy when the repo changes) work too: enable them in the stack settings after the first deploy.