The Builder: new instances

What the Builder does

Everything you build normally lands in one workspace, /opt/stacks/<your-client-code>-app. That is the right home for dashboards and for most apps, because they share the same data connections and the same audience.

The Builder creates a new, separate instance alongside it: another folder under /opt/stacks/, running in its own Docker containers, with its own database and its own address. Two instances on the same box share the hardware and share nothing else. A change in one cannot affect the other.

When a build deserves its own instance

Most work belongs in your main workspace. Creating an instance for every dashboard means eleven things to maintain instead of one. Four situations genuinely justify the separation.

Keep it in your main workspace when the answer to all of these is no. Shared context is a feature: a dashboard sitting beside your other dashboards inherits the definitions you have already taught the box.

What a new instance gets

Creating one

Before you create anything, decide four things. Writing them down takes two minutes and shapes everything after.

1. Name. Short, lowercase, hyphenated. See naming below.
2. Purpose. One sentence. "The customer-facing order portal."
3. Audience. Who logs in, and whether they are inside your organization.
4. Data. Which sources it needs, and whether it reads them directly or receives them from your main instance.

Then open the Builder on your box and create it. If you are unsure how the Builder works on your deployment, ask the box directly. It knows how it is configured, which is a faster answer than any document.

Explain how the Builder works on this box.

Tell me:
- how I open it, and whether that is a web page, a command, or something
  I ask you to do
- what happens when I create a new instance: what folders, containers,
  databases, and addresses get created
- what naming rules apply
- how a new instance gets its data connections
- how I list, stop, restart, and remove instances
- what limits exist: how many instances this box can reasonably run

Show me the current instances on this box and what each one is for.

Once you know the mechanics, this is the prompt that creates a well-formed instance:

Create a new instance called <instance-name>.

Purpose: <one sentence>.
Audience: <who logs in, and whether they are inside our organization>.

It needs:
- its own database, nothing shared with our main workspace
- <read access to: list the sources, or "no external data yet">
- sign-in required for every page, with <roles you need>
- to be reachable at <the address, or "tell me what address it gets">

Before you create anything, show me:
1. what you are about to create: folders, containers, database, address
2. anything that will change on the main workspace
3. how this instance will get the data it needs

Wait for my approval, then create it and tell me how to open it.

Naming, so future you can tell them apart

You will have four of these within a year, and the person opening them may not be you. A name that says what it is and who it is for beats a clever one.

Rules that keep everything predictable: lowercase, hyphens rather than spaces or underscores, no dates in the name, and a -sandbox suffix on anything you intend to delete.

Moving existing work into a new instance

A common path: something you built in your main workspace grew up and now needs its own walls. Move it deliberately rather than copying files by hand.

The <name> app in our main workspace has outgrown it and should move to its
own instance.

Plan the move before doing anything. Show me:
1. everything that belongs to this app: pages, database tables, scheduled
   jobs, configuration
2. anything shared with the rest of the workspace, and what breaks if it moves
3. which data connections it needs, and whether it should read them directly
   or receive data from the main instance
4. the order of operations, and what is unavailable during the move
5. how we roll back if it goes wrong

Change nothing yet. I want to read the plan and pick a time.

Managing what you have

Instances accumulate. Every quarter, look at what is running and turn off what is not being used. A stopped instance frees memory and stops being something to keep patched.

Give me a review of every instance on this box.

For each one:
- its name and what it is for
- whether it is running
- when anyone last used it
- what data sources it holds credentials for
- roughly how much memory and disk it is using

Then recommend which ones to stop, which to remove, and which to leave, with
a one-line reason each. Recommend only. Change nothing.

To see what is running without a conversation, from the box:

ls /opt/stacks
docker ps

The first lists every instance folder. The second lists the containers actually running right now.

Resources and housekeeping

Your box is a real computer with a fixed amount of memory. Each running instance takes a share, and an instance that is idle still holds its memory. There is a practical ceiling on how many run at once.

• Stop what you are not using. The fastest way to make a slow box fast again.
• Keep experiments named as experiments. A -sandbox suffix makes the quarterly cleanup a two-minute job.
• Watch disk as well as memory. Each instance keeps its own database and its own logs, and logs grow quietly.
• Ask before adding the fifth. If instances are multiplying, that is worth a conversation about whether the box is sized right for what you are now doing with it.