Development environments

A dev environment is a code project, not a copy of a website. It is one record (datatype: "dev_environment") that names a project the platform's hosting partner builds and runs. People work on it in Vibe Studio. It has two addresses of its own:

Both addresses come from container-management.service.ts 350–360 and are set when the record is made (dev-environment.service.ts 127–157). Paths below are appengine src/site/ unless they say otherwise.

Ask first

• What do they want to do? Build a separate app in Vibe Studio: this skill. Try changes on their website: use the pages linked above.
• The name. Lowercase letters, numbers, hyphens and underscores. It becomes part of both addresses and can't be changed later.
• A title and description, if they want them. Otherwise the engine writes "<name> Development Environment".
• Who should get into it? Only staff of this org can be invited (step 4). Never guess an address.
• Deleting: which one, by name. Say it can't be undone.

Steps

1. Sites & Dev Environments: what's there and the room left

repo_find on dev_environment with {} lists them. Read data.name, data.productionUrl, data.previewUrl, data.domains and data.config.status.

call_appengine GET /site/limits returns the plan's limits against what the org uses (plan-validation.service.ts 172–231). The item with key: "devEnvironments" has used, limit and state (ok, warning at 80%, full, or unknown). Tested on a local org:

{ "key": "devEnvironments", "label": "Dev environments", "used": 0, "limit": 1, "usedText": "0", "limitText": "1", "percent": 0, "state": "ok" }

How many each plan allows is in Plans and pricing (usage/pricing-plan.ts). Every dev environment record counts, whatever its status.

Hands on: the names already used, and used / limit. Check: Studio › DAM › Site & Dev Environments (/site-management), the Dev Environments tab, shows the same list. Each card shows its production address, status and domain count.

2. Sites & Dev Environments: create one

In Studio: New Dev Env › Create Dev Environment: Environment Name (required), Title, Description › Create Environment (websitemint site-management/modern-site-app.tsx 215–259, 1088–1157). The box turns any other character into - as it is typed.

Through the API: call_appengine POST /dev-env/create with

{ "name": "<name>", "title": "<title>", "description": "<description>" }

What happens (dev-environment.service.ts 117–197):

1. The plan is checked. At the limit it answers 403 "<Plan> plan allows maximum N development environment(s). Current: X. Upgrade your plan to create more." Studio opens its upgrade window instead.
2. The record is made with the fields in the table above, config.status: "draft".
3. The org's own email address gets the dev-environment-created email, with a link that signs them in to Vibe Studio on this environment.

It answers { devEnvironment, name, orgId, productionUrl, devUrl, previewUrl }. The hosting partner (SpinForge) reads this record to set up the project (dev-environment.service.ts 41–99); the engine itself builds and starts nothing.

Who may: a signed-in person with the ContentAdmin or ConfigAdmin role, or an org API key allowed admin routes (dev-environment.controller.ts 34–41).

Stop: creating one takes a slot on the plan, emails the org's address and sets up hosting for a new project. Show the name, the two addresses it will have and the slots left, and wait for yes. Check first that no environment already has the name.

Hands on: the name, productionUrl and previewUrl. Check: the new card on the Dev Environments tab; call_appengine GET /dev-env/get/<name> returns the record (404 "Dev environment not found" for a wrong name, tested).

3. Vibe Studio: open it and work on it

On the card: Open Vibe Studio (the first button), or … › Copy Dev URL. Both ask the engine for a one-time sign-in token for the person clicking (POST /profile/session-access with { "handoff": "vibe-studio", "devEnvName": "<name>" }, appengine users/users.controller.ts 749–757) and open https://vibe-studio.appmint.io/login?orgId=…&email=…&token=…&devEnv=<name> (modern-site-app.tsx 431–466). Without a session it falls back to the production address.

The work itself (the code, building, publishing) happens in Vibe Studio, not in this engine. See Vibe Studio.

Check: Vibe Studio opens on the environment, signed in.

4. Vibe Studio: invite a staff member

There is no button for this in Studio. call_appengine POST /dev-env/send-session-invitation with

{ "devEnvironment": "<name>", "toEmail": "<their email>" }

The address must belong to a user of this org (404 "User not found" otherwise; customers can't be invited). The engine emails them from APPMINT [email protected], subject "Invitation to <name> Development Environment", with a link that signs them in to Vibe Studio on it (dev-environment.service.ts 584–630). The email says the link lasts 15 minutes and works once.

Stop: this emails a person. Name them and the environment, and wait for yes.

Check: the answer is { "status": "success", "message": "Invitation sent to <email>" }.

5. Review it

• Preview: the card's Preview Environment button opens https://<previewUrl>, the working preview.
• Production: the address under the name on the card, https://<productionUrl>.
• Details: … › View Details, or the settings button, shows name, title, description, both addresses, its domains and its Kubernetes resources.

The engine doesn't build the project. If an address doesn't answer yet, say so; don't promise when it will.

Check: open both and say what each shows.

6. A custom domain on it

… › Attach Domain, or call_appengine POST /dev-env/attach-domain/<name> with { "domainName": "<domain>" }. The plan must allow custom domains. The domain is lowercased, checked for shape and added to domains only (dev-environment.service.ts 372–422). No route or certificate is made: the lines that would do it are commented out (399–403). Studio then shows DNS instructions, but the domain won't reach the environment.

Removing: Studio's Remove says "Dev environment domain removal not yet implemented" (modern-site-app.tsx 303–306). The API's POST /dev-env/detach-domain/<name> with { "domainName": "<domain>" } takes it off the list (dev-environment.service.ts 424–446).

For a site's domain, which does work, see Connect a custom domain.

Check: View Details › Domains lists it. Tell the person it isn't live.

7. Sites & Dev Environments: delete one

… › Delete Environment ("This will permanently delete the dev environment … and all its K8s resources. This action cannot be undone.") or call_appengine DELETE /dev-env/<name> with confirmed: true.

What happens (dev-environment.service.ts 229–351), each part best effort so one failure doesn't block the rest:

• its hosting is torn down: both the production and the preview project, with their builds and aliases;
• its API key <name>-<org>-dev-env-key, if there is one, is deleted;
• the record is deleted, and the slot is free again;
• the org's address gets the dev-environment-deleted email.

Stop: the project and both addresses are gone for good. Say which environment, that it can't be undone and that the owner will be emailed, and wait for yes.

Check: the card is gone; GET /dev-env/get/<name> is 404; GET /site/limits shows one fewer used.

Turning a site into a dev environment

POST /dev-env/convert/<site name> with { "framework": "", "templateRepo": "" } makes a new dev environment named after the site, with the site's title and description (dev-environment.service.ts 199–227). The site is untouched and none of its pages go with it. It is the same as step 2, Stop included.

Server controls (platform staff)

The engine also has status, logs, start, stop, restart and rebuild for an environment's container (GET /dev-env/<name>/status, /logs; POST /dev-env/<name>/start, /stop, /restart, /rebuild). Each needs config.containerDomain on the record, which nothing in the engine writes, so they answer 404 "Container domain not found for this environment". The cluster itself is run by platform staff (see Platform operations). Don't offer these to the person.

When it's done

Tell the person: the environment's name, its production and preview addresses, its status, how many of the plan's dev environments are now used, who was emailed (the org's address on create and delete, an invited person), and that its domains are recorded only. Open Site & Dev Environments on the Dev Environments tab.

What it can't do yet

• No link to a site. A dev environment can't be made from a site's pages or promoted onto a site.
• Custom domains are recorded, not routed, and can't be removed in Studio.
• Start, stop, restart, rebuild, status and logs answer 404 on every environment the engine makes.
• Enable hosting (POST /dev-env/enable-hosting/<name>) only returns the record; it changes nothing (dev-environment.service.ts 353–370).
• No invite button in Studio, and only org users can be invited.
• The name can't be changed, and the title and description have no edit screen.
• BusinessMade orgs get 1 dev environment, though their plans list 0.

Don'ts

• Don't create a dev environment when the person wants to try changes on their website; clone the site or use page preview and History.
• Don't create one, invite anyone or delete one without a yes.
• Don't share a Copy Dev URL link; invite the person instead.
• Don't tell the person an attached domain is live.
• Don't say a dev environment was promoted or deployed to the site; there is no such step.
• Don't use Make Active on a dev environment; it is for sites.