github/penpot
1
0
Fork 0
mirror of https://github.com/penpot/penpot.git synced 2026-06-09 08:52:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

✨ Add the ability to launch parallel devenv instances (#9906)

Browse Source 
* 🐳 Split devenv compose for parallel workspaces

Move shared services into an infra compose file and keep the main devenv container plus Valkey in a separate compose file driven by defaults.env. Parameterize host-side ports, container names, source path, and runtime env while keeping container-internal ports fixed for same-origin proxying.

Make tmux startup idempotent, add attach-devenv for the live instance, move shared MinIO user setup to infra startup, and let exporter scripts load backend _env.local overrides.

Co-authored-by: Codex <codex@openai.com>

* 🐳 Run parallel devenv instances against shared infra

Add support for running N parallel devenv instances under separate compose
projects sharing Postgres, MinIO, mailer, and LDAP. Each instance has its
own main container, Valkey, source checkout, tmux session, and host port
range offset by 10000 (3449 -> 13449 -> 23449, etc.).

./manage.sh run-devenv-agentic --n-instances N reconciles the running set
to exactly {ws0..ws(N-1)}: missing instances are created (workspace sync
from the live repo via git ls-files + per-instance env-file generation
under docker/devenv/instances/ + detached tmux startup), surplus instances
are stopped highest-first via compose down (never -v), already-running
instances are left untouched. ws0 binds the live repo at PWD; ws1+ are
scratch clones under ~/.penpot/penpot_workspaces/.

Backend workers (enable-backend-worker) are gated on PENPOT_BACKEND_WORKER
in backend/scripts/_env; ws1+ overlays disable them so async-task
notifications stay bound to a single Valkey Pub/Sub instance.

Compose helpers wrap docker compose with env -i so per-instance overlay
--env-file actually overrides defaults.env -- without the strip, the shell
env from sourcing defaults.env at startup would shadow the overlay (Compose
gives shell precedence over --env-file).

Other:
- Drop network aliases (- main, - redis); use container_name for
  cross-container DNS so multiple instances on the shared network don't
  fight over the same DNS name.
- Pin volume names via name: (PENPOT_*_VOLUME) so volumes survive project
  renames; ws0 keeps the pre-existing physical names (penpotdev_*).
- Remove cross-project depends_on from main.yml (postgres/minio-setup now
  live in penpotdev-infra); manage.sh ensure-infra-up docker-waits on the
  minio-setup one-shot.
- Strict arg parsing in run-devenv / run-devenv-agentic; --n-instances 0
  rejected.
- Remove unused Host-matched server block from the Caddyfile.

Memory mem:devenv/core and developer docs updated.

Co-authored-by: Codex <codex@openai.com>

* ✨ Document and stabilise the parallel-workspace CLI; wire AI agents

Improve parallel-workspaces developer CLI,
and add an opt-in layer that lets four AI
coding agents (Claude Code, opencode, VS Code Copilot, OpenAI Codex CLI)
drive a specific workspace through a single launcher command.

Parallel-workspace semantics
----------------------------

each run-devenv-agentic call brings up one wsN;
--ws N (integer; default 0) targets a specific workspace and auto-starts
ws0 first when N>=1 so the worker invariant holds. --sync is forbidden on
ws0 and re-seeds the workspace from the live repo for ws1+. Stop semantics
mirror the start invariant -- ws0 is the last to stop, shared infra stops
with it, --all walks every instance highest-first. The worker policy
section explains why workers run only on ws0 (Postgres FOR UPDATE
SKIP LOCKED is safe across many workers but the cron dedup primitive is
best-effort, and :telemetry / :audit-log-archive are not idempotent).
Per-instance Valkey Pub/Sub isolation, msgbus topology, and the
"async task notifications miss ws1+ tabs" caveat are stated explicitly.

The mem:prod-infra/core memory captures the same external-services and
task-queue / Pub-Sub topology in agent-readable form, and
mem:backend/core and mem:critical-info now cross-link it so backend work
surfaces the horizontal-scaling constraints from the start.

AI coding agent integration
---------------------------

New top-level .devenv/ directory holds committed templates
(templates/{claude-code,opencode,vscode}.json and templates/codex.toml,
each with \${PENPOT_MCP_PORT} and \${SERENA_MCP_PORT} placeholders) plus
committed shared entries (matching shared/* files for Playwright, the
only workspace-independent server we ship today).

./manage.sh start-coding-agent <claude|opencode|vscode|codex> [--ws N]
launches the chosen client against one workspace. It cd's into the
target's directory (the live repo for ws0; workspace-path "wsN" for ws1+)
and refuses to launch unless (a) the binary is on PATH, (b) the
workspace directory exists for ws1+, and (c) the instance is up
(devenv-main-running) -- the MCP servers only exist while the devenv is
running. The agentic-devenv guide is restructured around this Quick
start path, with a per-client table and a Manual configuration fallback
for clients we don't cover.

Co-Authored-By: Codex <codex@openai.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ♻️ Scope the shadow devtools to the dev build

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michael Panchenko 2026-06-03 15:48:25 +02:00 committed by GitHub
parent 88f50b6ddd
commit 16dc83616a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
30 changed files with 2338 additions and 373 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
.devenv/README.md Normal file
View File

@ -0,0 +1,133 @@
# `.devenv/` — Per-Workspace AI-Client MCP Configs
This directory carries the pieces needed to point an AI coding agent
(currently Claude Code, opencode, VS Code Copilot, and the OpenAI Codex CLI)
at the MCP servers running inside the parallel devenv instance the developer
is currently working in. Every parallel workspace (`ws0`, `ws1`, …) has its
own copy because the Penpot MCP and Serena MCP host ports are
workspace-specific.
## Layout
```
.devenv/
README.md
scripts/
merge-mcp-config.py # generator helper invoked by manage.sh
shared/ # committed; workspace-independent entries
claude-code.json # Playwright — same for every workspace
opencode.json
vscode.json
codex.toml
templates/ # committed; entries with ${...} port placeholders
claude-code.json # Penpot MCP, Serena MCP — port is the only diff
opencode.json
vscode.json
codex.toml
mcp/ # gitignored; written by manage.sh per workspace
claude-code.json # loaded via Claude Code's --mcp-config flag
opencode.json # loaded via OPENCODE_CONFIG env var
```
One more file is generated outside `.devenv/`, in the directory VS Code itself
auto-discovers (gitignored):
```
.vscode/mcp.json # auto-loaded by GitHub Copilot in VS Code
```
Codex is the exception: it has no way to load an MCP config from an arbitrary
path, and its only project-level config file (`.codex/config.toml`) is one a
developer may already own. So we do **not** write a file for Codex at all —
`start-coding-agent codex` injects our servers as `-c` command-line overrides
built fresh from `shared/codex.toml` + `templates/codex.toml` at launch.
* **`shared/`** holds MCP entries that don't depend on the workspace — the
browser-driving Playwright server today, plus any other workspace-independent
servers we add later. Same content in every workspace, so it's a static
checked-in file.
* **`templates/`** holds the workspace-specific entries (Penpot MCP, Serena
MCP) with `${PENPOT_MCP_PORT}` and `${SERENA_MCP_PORT}` placeholders. The
placeholders are resolved per-workspace from the port-base constants in
`manage.sh`.
* **`mcp/`** (Claude Code, opencode) is the result of merging `shared/` with
the port-substituted `templates/`. `manage.sh` writes these on every
`run-devenv-agentic` pass. Gitignored, dedicated paths with no developer
content — never edit by hand, your edits will be overwritten on the next
reconcile.
* **`.vscode/mcp.json`** is the same merge, but written to the path VS Code
auto-discovers. Because on `ws0` that path *is* the live repo's own file, the
reconcile **deep-merges** into it: any servers you added yourself are kept,
and only the entries we manage (`penpot`, `serena-devenv`, `playwright`) are
(re)written to the current ports. On `ws1+` the file doesn't exist yet, so it
is created from scratch.
* **`scripts/merge-mcp-config.py`** is the generator. Its `json` mode does the
JSON deep-merge (with `--merge-into-existing` for the VS Code path); its
`codex-args` mode prints the `-c` assignments for Codex. `manage.sh`'s
`_merge-mcp-config-json` helper is a thin shim over the former, and
`start-coding-agent` calls the latter directly. Run
`python3 .devenv/scripts/merge-mcp-config.py --help` for the CLI.
## Launching a coding agent
The easiest path is the wrapper command, which knows the right flags per
client, `cd`'s into the target workspace, and refuses to launch unless the
target instance is running and its MCP config has been generated:
```bash
# Default target is ws0 (the live repo).
./manage.sh start-coding-agent claude [...args to forward]
./manage.sh start-coding-agent opencode [...args to forward]
./manage.sh start-coding-agent vscode [...args to forward to 'code']
./manage.sh start-coding-agent codex [...args to forward]
# Target a parallel workspace with --ws N. N is an integer (non-negative);
# 'main', 'ws1' and similar spellings are rejected.
./manage.sh start-coding-agent claude --ws 1
./manage.sh start-coding-agent opencode --ws 2
```
Equivalents by hand (run from inside the workspace directory):
```bash
claude --mcp-config .devenv/mcp/claude-code.json
OPENCODE_CONFIG=.devenv/mcp/opencode.json opencode
code "$PWD" # VS Code auto-discovers .vscode/mcp.json
# Codex: pass our servers as -c overrides (no config file is written).
codex $(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
.devenv/shared/codex.toml .devenv/templates/codex.toml \
| sed 's/^/-c /')
```
`start-coding-agent codex` does the `-c` wiring for you (and resolves the
workspace's ports first). Because our servers arrive as command-line
overrides, no "trusted project" prompt is involved for them — that prompt only
gates Codex's own `.codex/config.toml`, which we never write.
## Overriding our entries
Both the auto-discovered configs and the launcher-loaded configs sit *on top
of* the developer's global config (with varying precedence rules). All four
clients offer escape hatches for shadowing entries we ship:
* **Claude Code** — `claude mcp add --scope local …` installs a private entry
that overrides the one in `mcp/claude-code.json`. Local scope wins.
* **opencode** — drop an `opencode.json` at the repo root with the override
entries you need. opencode's precedence chain is *global → `OPENCODE_CONFIG`
→ project*, so the project file always wins. The root `opencode.json` is
gitignored on purpose, since these overrides are personal.
* **VS Code Copilot** — the reconcile deep-merges into `.vscode/mcp.json`, so
any servers you add there yourself are preserved (only `penpot`,
`serena-devenv` and `playwright` are rewritten). To shadow one of *ours*,
put an entry under the same name in your VS Code user-profile MCP config —
it is loaded alongside the workspace file and wins.
* **Codex CLI** — our servers arrive as `-c` overrides, which are Codex's
highest-precedence layer, so they win over a same-named `[mcp_servers.<name>]`
in your `~/.codex/config.toml` or a project `.codex/config.toml`. To override
one of ours, append your own `-c` after the client name — extra args are
forwarded after ours and the later `-c` wins, e.g.
`./manage.sh start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`.
See `docs/technical-guide/developer/agentic-devenv.md` for the broader
client-configuration story (browser remote debugging, AI-client config
schemas, manual setup for unsupported clients).

204
.devenv/scripts/merge-mcp-config.py Executable file
View File

@ -0,0 +1,204 @@
#!/usr/bin/env python3
"""Combine a shared MCP-server config with a port-substituted template for one
AI coding-agent client.
Invoked per workspace by manage.sh's `write-instance-mcp-configs` (JSON
clients) and by `start-coding-agent` (Codex). Each supported client ships a
`.devenv/shared/<tool>.{json,toml}` (workspace-independent entries, e.g.
Playwright) and a `.devenv/templates/<tool>.{json,toml}` (per-workspace entries
with `${PENPOT_MCP_PORT}` / `${SERENA_MCP_PORT}` placeholders). This script
combines the two for the target client.
Two output modes are supported:
json Deep-merge two JSON documents under a configurable top-level key
(`mcpServers` for Claude Code, `mcp` for opencode, `servers` for
VS Code Copilot) and write the result to <out>. Same-name
entries in the template override entries in shared. With
--merge-into-existing, any pre-existing <out> file is loaded as
the lowest-precedence layer first, so entries the developer
already had are preserved (ours win on name collision). This is
used for VS Code's auto-discovered `.vscode/mcp.json`, which on
ws0 IS the live repo's file and may hold the developer's own
servers; the Claude/opencode outputs live in a dedicated,
gitignored `.devenv/mcp/` path and are written without the flag
(a clean overwrite).
codex-args Deep-merge the two TOML chunks and print one
`dotted.key=<toml-value>` assignment per line to stdout (no
<out> file). The caller wraps each line in a `codex -c` flag.
Codex has no way to load an MCP config from an arbitrary file
path (CODEX_HOME would relocate auth/history too), so rather than
writing the auto-discovered `.codex/config.toml` we inject our
servers as ephemeral per-invocation overrides. This never
touches the developer's project- or user-level Codex config.
In both modes, `${VAR}` placeholders inside *either* chunk are resolved from
the current environment (only template chunks carry placeholders in practice,
but the substitution is uniform either way) using Python's
`os.path.expandvars`. Undefined placeholders are left as `${VAR}` literal text
-- callers (i.e. manage.sh) are responsible for exporting the variables before
invoking the script.
Usage:
merge-mcp-config.py --format json --key <key> [--merge-into-existing] \
<shared> <template> <out>
merge-mcp-config.py --format codex-args <shared> <template>
Exit codes:
0 success
2 argparse error (missing required option, bad value, unreadable input)
"""
from __future__ import annotations
import argparse
import json
import os
import re
import sys
import tomllib
from pathlib import Path
def merge_json(
shared_path: Path,
tpl_path: Path,
out_path: Path,
key: str,
merge_into_existing: bool,
) -> None:
"""Deep-merge JSON documents under a single top-level dict key into out.
Precedence (lowest to highest): an existing <out> file (only when
merge_into_existing is set), then shared, then the template. Entries under
`key` are merged by name, so the template wins on a name collision while
every other entry the lower layers contributed is kept. Top-level keys
other than `key` come from the existing file and shared (shared wins).
"""
shared = json.loads(shared_path.read_text())
tpl = json.loads(os.path.expandvars(tpl_path.read_text()))
base: dict = {}
if merge_into_existing and out_path.exists():
base = json.loads(out_path.read_text())
merged: dict = {**base, **shared}
merged[key] = {**base.get(key, {}), **shared.get(key, {}), **tpl.get(key, {})}
out_path.write_text(json.dumps(merged, indent=2) + "\n")
def _deep_merge(base: dict, overlay: dict) -> dict:
"""Recursively merge overlay into base; overlay wins on scalar/list keys."""
out = dict(base)
for k, v in overlay.items():
if isinstance(out.get(k), dict) and isinstance(v, dict):
out[k] = _deep_merge(out[k], v)
else:
out[k] = v
return out
def _toml_value(value: object) -> str:
"""Serialize a scalar/list as a TOML literal for a `codex -c` value.
bool is checked before int because `isinstance(True, int)` is True. Strings
are emitted as JSON strings, which are valid TOML basic strings for the
ASCII values our configs carry (commands, args, URLs). Tables never reach
here -- they are flattened into dotted keys by _flatten.
"""
if isinstance(value, bool):
return "true" if value else "false"
if isinstance(value, (int, float)):
return repr(value)
if isinstance(value, str):
return json.dumps(value)
if isinstance(value, list):
return "[" + ", ".join(_toml_value(v) for v in value) + "]"
raise TypeError(f"unsupported TOML value type: {type(value).__name__}")
_BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
def _key_segment(seg: str) -> str:
"""A dotted-key segment: bare if TOML-safe, else a quoted key."""
return seg if _BARE_KEY.match(seg) else json.dumps(seg)
def _flatten(obj: dict, prefix: list[str]):
"""Yield (dotted-path-segments, leaf-value) for every non-table leaf.
Lists are leaves (TOML arrays), so we do not recurse into them; nested
tables (e.g. an `env` table) are flattened into further dotted keys.
"""
for k, v in obj.items():
path = prefix + [k]
if isinstance(v, dict):
yield from _flatten(v, path)
else:
yield path, v
def emit_codex_args(shared_path: Path, tpl_path: Path) -> None:
"""Print `dotted.key=<toml-value>` lines from the merged TOML chunks."""
shared = tomllib.loads(os.path.expandvars(shared_path.read_text()))
tpl = tomllib.loads(os.path.expandvars(tpl_path.read_text()))
merged = _deep_merge(shared, tpl)
for path, value in _flatten(merged, []):
dotted = ".".join(_key_segment(s) for s in path)
sys.stdout.write(f"{dotted}={_toml_value(value)}\n")
def main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(
description=__doc__.split("\n\n", 1)[0],
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument(
"--format",
choices=("json", "codex-args"),
required=True,
help="Output mode: 'json' writes a merged file; 'codex-args' prints -c assignments.",
)
parser.add_argument(
"--key",
help="Top-level JSON key under which MCP entries live (required for --format json).",
)
parser.add_argument(
"--merge-into-existing",
action="store_true",
help="json only: layer the merge on top of an existing <out> file, "
"preserving entries already there (ours still win on name collision).",
)
parser.add_argument("shared", type=Path, help="Path to the shared chunk.")
parser.add_argument("template", type=Path, help="Path to the port-placeholder template chunk.")
parser.add_argument(
"out",
type=Path,
nargs="?",
help="Path the merged result is written to (json only; codex-args writes stdout).",
)
args = parser.parse_args(argv)
if args.format == "json":
if not args.key:
parser.error("--key is required when --format json")
if args.out is None:
parser.error("out is required when --format json")
merge_json(args.shared, args.template, args.out, args.key, args.merge_into_existing)
else: # codex-args
if args.key:
parser.error("--key is not accepted when --format codex-args")
if args.merge_into_existing:
parser.error("--merge-into-existing is not accepted when --format codex-args")
if args.out is not None:
parser.error("out path is not accepted when --format codex-args (result goes to stdout)")
emit_codex_args(args.shared, args.template)
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))

8
.devenv/shared/claude-code.json Normal file
View File

@ -0,0 +1,8 @@
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
}
}
}

8
.devenv/shared/codex.toml Normal file
View File

@ -0,0 +1,8 @@
# Workspace-independent MCP servers for the OpenAI Codex CLI.
# This block is concatenated with the port-substituted templates/codex.toml
# by manage.sh's write-instance-mcp-configs to produce .codex/config.toml at
# the workspace root.
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]

9
.devenv/shared/opencode.json Normal file
View File

@ -0,0 +1,9 @@
{
"mcp": {
"playwright": {
"type": "local",
"command": ["npx", "@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"],
"enabled": true
}
}
}

9
.devenv/shared/vscode.json Normal file
View File

@ -0,0 +1,9 @@
{
"servers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
}
}
}

12
.devenv/templates/claude-code.json Normal file
View File

@ -0,0 +1,12 @@
{
"mcpServers": {
"penpot": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:${PENPOT_MCP_PORT}/mcp", "--allow-http"]
},
"serena-devenv": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:${SERENA_MCP_PORT}/mcp", "--allow-http"]
}
}
}

10
.devenv/templates/codex.toml Normal file
View File

@ -0,0 +1,10 @@
# Workspace-specific MCP servers for the OpenAI Codex CLI. The PENPOT_MCP_PORT
# and SERENA_MCP_PORT placeholders below are filled in per workspace by
# manage.sh's write-instance-mcp-configs, then the result is concatenated
# with shared/codex.toml to produce .codex/config.toml.
[mcp_servers.penpot]
url = "http://localhost:${PENPOT_MCP_PORT}/mcp"
[mcp_servers.serena-devenv]
url = "http://localhost:${SERENA_MCP_PORT}/mcp"

14
.devenv/templates/opencode.json Normal file
View File

@ -0,0 +1,14 @@
{
"mcp": {
"penpot": {
"type": "remote",
"url": "http://localhost:${PENPOT_MCP_PORT}/mcp",
"enabled": true
},
"serena-devenv": {
"type": "remote",
"url": "http://localhost:${SERENA_MCP_PORT}/mcp",
"enabled": true
}
}
}

12
.devenv/templates/vscode.json Normal file
View File

@ -0,0 +1,12 @@
{
"servers": {
"penpot": {
"type": "http",
"url": "http://localhost:${PENPOT_MCP_PORT}/mcp"
},
"serena-devenv": {
"type": "http",
"url": "http://localhost:${SERENA_MCP_PORT}/mcp"
}
}
}

3
.gitignore vendored
View File

@ -95,4 +95,7 @@
/.idea
/.claude
/.playwright-mcp
/.devenv/mcp/
/opencode.json
/.codex/
/tools/__pycache__

1
.serena/memories/backend/core.md
View File

@ -7,6 +7,7 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; m
- RPC, DB helpers, workers, cron: `mem:backend/rpc-db-worker-subtleties`
- HTTP sessions, config, storage, media, file data persistence: `mem:backend/http-storage-filedata-subtleties`
- Auth flows, permission model, teams, projects, invitations, comments, webhooks, audit: `mem:backend/auth-permissions-product-domains`
- Services, task-queue/Pub-Sub topology constraints -> `mem:prod-infra/core`.
## Stable namespace map

10
.serena/memories/critical-info.md
View File

@ -13,15 +13,15 @@ You are working on the GitHub project `penpot/penpot`, a monorepo.
- You have access to the GitHub CLI `gh` or corresponding MCP tools.
- Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool.
- Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps.
* After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
*After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
- Never run anything that destroys data without explicit permission, including `drop-devenv`, `docker compose down -v`, `docker volume rm ...`. The user's real work lives in the volumes of the shared infra.
# Project modules
This is a monorepo. Principles that apply to one module do *not* generally apply to others. Do not make assumptions.
- `frontend/`: ClojureScript + SCSS SPA/design editor.
- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers.
- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers.Runtime services and the task-queue vs Pub/Sub topology that constrains horizontal scaling: `mem:prod-infra/core`.
- `common/`: shared CLJC data types, geometry, schemas, file/change logic, and utilities.
- `render-wasm/`: Rust -> WebAssembly Skia renderer consumed by frontend.
- `exporter/`: ClojureScript/Node headless Playwright SVG/PDF export.
@ -36,7 +36,9 @@ module. You can read it from `mem:<MODULE>/core`
# Low-centrality project paths
- `docker/` contains devenv related code, not needed unless specifically instructed.
More info in docs/technical-guide if instructed to work on this.
When working on devenv startup, compose layout, instance config (`defaults.env`),
tmux session lifecycle, MinIO provisioning, or anything in `manage.sh`'s
`*-devenv` commands, read `mem:devenv/core`.
- `experiments/` contains standalone experimental HTML/JS/scripts; treat it as non-core unless the user explicitly asks about it.
- `sample_media/` contains sample image/icon media and config used as fixtures/demo material; do not infer app behavior from it.

73
.serena/memories/devenv/core.md Normal file
View File

@ -0,0 +1,73 @@
# Devenv startup and configuration
Compose-based dev environment under `docker/devenv/`, driven by `manage.sh`. Parallel instances share infra + Postgres + MinIO; each instance has its own `main` container, Valkey, source checkout, tmux session.
## Compose project layout
- `penpotdev-infra`: shared `postgres`, `minio`, `minio-setup`, `mailer`, `ldap`. File: `docker-compose.infra.yml`.
- `penpotdev-wsN` (N=0,1,…): per-instance `main` + `redis` (Valkey). File: `docker-compose.main.yml`. ws0 (a.k.a. `main`) binds `$PWD`; ws1+ bind clones at `${PENPOT_WORKSPACES_DIR}/wsN/` (default `~/.penpot/penpot_workspaces/`), maintained by the developer.
- All projects join external network `penpot_shared`. Created idempotently by `ensure-devenv-network`, never removed by lifecycle commands.
## Source-of-truth files
- `docker/devenv/defaults.env`: ws0 baseline — container/volume names, runtime env, published host ports, tmux defaults. `manage.sh` aborts if unreadable.
- For ws1+, `instance-env-overrides` computes the per-instance overrides (container/volume names, host ports offset `10000·N`, `PENPOT_PUBLIC_URI`, `PENPOT_REDIS_URI`, `PENPOT_BACKEND_WORKER=false`) and `instance-compose` injects them as env vars at compose time — never written to disk, recomputed each call so they can't drift. ws0 uses `defaults.env` as-is.
- `backend/scripts/_env`: backend-internal only — secret keys, `PENPOT_FLAGS` (with `enable-backend-worker` gated on `PENPOT_BACKEND_WORKER`), `JAVA_OPTS`, `setup_minio()`. Never duplicates `defaults.env`.
- Compose files use pure `${VAR}` substitution; missing var = compose fails.
## Invariants
- `infra-compose` / `instance-compose` wrap `docker compose` with `env -i`, then re-inject what compose needs. Stripping is required because `defaults.env` is sourced into manage.sh's shell at startup (stale values would leak); the ws1+ overrides are deliberately re-injected as shell env vars precisely because Compose gives shell precedence over `--env-file`, so they override the `defaults.env` baseline.
- Volume names pinned via `name:` (PENPOT_*_VOLUME), decoupled from the compose project name. ws1+ inject distinct per-instance volume names; ws0 keeps the historical `penpotdev_*` physical names so project renames never require data migration.
- Network aliases (`- main`, `- redis`) are not declared in main.yml. Compose's auto-service-alias still registers `redis` on the shared network, so DNS for `redis` is non-deterministic with multiple instances. Backend uses `PENPOT_REDIS_URI=redis://penpot-devenv-wsN-valkey/0` (container_name) instead.
- No cross-project `depends_on`. `manage.sh ensure-infra-up` `docker wait`s on the `minio-setup` one-shot.
- `JAVA_OPTS` in `manage.sh` is shadowed inside the container by `_env`. The `-e JAVA_OPTS=...` flag only matters for processes that don't source `_env`.
## Worker policy
Backend workers run only on ws0. `_env` gates `enable-backend-worker` on `PENPOT_BACKEND_WORKER`; ws1+ inject it as false. ws0 must be running whenever any ws1+ is running, and is the last instance to stop — `run-devenv-agentic --ws N` (N≥1) auto-starts ws0 first; `stop-devenv` refuses to stop ws0 while any ws1+ is up. Workers are pure fire-and-forget: `wrk/submit!` inserts a row into the shared Postgres `task` table and returns; RPC handlers never wait on completion and workers never publish to msgbus. The reason for "ws0 only" is avoiding multi-instance worker races (cron dedup is best-effort across instances, `wrk/submit!` `dedupe` is racy across submitters); details in `mem:prod-infra/core`.
## Port layout
Container-internal ports fixed; host side offset `10000·N`.
| ws0 | ws1 | wsN | container | role |
|---|---|---|---|---|
| 3449 | 13449 | 3449+10000·N | 3449 | public HTTPS (Caddy; `/mcp/ws` same-origin) |
| 3449/udp | 13449/udp | … | 3449/udp | HTTP/3 |
| 4401 | 14401 | … | 4401 | MCP HTTP stream |
| 4403 | 14403 | … | 4403 | MCP REPL |
| 14181 | 24181 | … | 14281 | Serena MCP |
| 14182 | 24182 | … | 24282 | Serena dashboard |
Everything else (frontend dev, backend API, exporter, storybook, REPLs, plugin dev, MCP inspector/WebSocket) is in-process or same-origin via Caddy/nginx. Infra publishes: mailer 1080, ldap 10389/10636 (singletons, not offset).
## Tmux + MCP routing
`docker/devenv/files/start-tmux.sh` is session-level idempotent. Reads `PENPOT_TMUX_ATTACH`. If the session exists it attaches or exits; otherwise creates 4 base windows (frontend watch / storybook / exporter / backend) plus `mcp` (when `enable-mcp` in `PENPOT_FLAGS`) and `serena` (when `SERENA_ENABLED=true`). `run-devenv-agentic` always sets both env vars. The legacy `run-devenv` alias doesn't, hence its 4-window-only session. To switch from a legacy session to agentic, `stop-devenv` then `run-devenv-agentic` — the conditional windows are only added at session create time.
MCP plugin routing is same-origin: frontend uses `<public-uri>/mcp/ws`, per-instance nginx proxies to MCP port 4401 in-container. For the plugin↔MCP server wiring (how the browser plugin discovers the URL, the in-memory connection registry, why DB-mediated routing isn't needed), see `mem:mcp/core`.
## Workspace orchestration (ws1+)
Workspace directories are user-maintained at `${PENPOT_WORKSPACES_DIR}/wsN`. `run-devenv-agentic --ws i` syncs only when `--sync` is passed, with one exception: if the workspace directory is missing on first use, sync runs implicitly to seed it.
`sync-workspace wsN`:
1. `assert-clean-git-state` — refuses on `.git/{rebase-apply,rebase-merge,MERGE_HEAD,CHERRY_PICK_HEAD,index.lock}`. No `--sync-force` escape.
2. `rsync -a --delete $PWD/.git/ $workspace/.git/`.
3. `git ls-files -z --cached --others --exclude-standard` → `rsync --files-from` (Git is the authority on tracked files; rsync's gitignore filter would drop committed files under gitignored parents like `.clj-kondo/config.edn`).
4. Initial-only copy of `frontend/resources/public/js/config.js` (gitignored, but agentic mode needs it). After the first sync the workspace's copy belongs to the developer — subsequent syncs leave it alone.
5. `git switch -C "wsN/<current-branch>"` inside the workspace.
No `--delete` on the working-tree pass: gitignored caches in the workspace survive. Workspace dir + named volumes survive `compose down`.
## CLI surface
- `run-devenv-agentic [--ws main|0|wsN|N] [--sync] [--serena-context CTX]`: bring one instance up. Agentic only — MCP and Serena windows are always created. Default target main. Errors out if the target is already running. `--sync` is rejected on main; on ws1+ it's optional (forced only when the workspace dir does not exist yet). Auto-starts ws0 first when the target is ws1+ and ws0 is not yet up.
- `stop-devenv [--ws main|0|wsN|N] [--all]`: stop instances. Flags mutually exclusive. `--ws N` (N≥1) stops just that workspace. `--ws 0` or no flag stops ws0 + shared infra, refused while any ws1+ is running. `--all` stops every ws highest-first then ws0, then infra.
- `run-devenv`: legacy alias, ws0 non-agentic attached.
- `attach-devenv [--ws main|0|wsN|N]`: pure attach. Fails fast if instance/session missing.
- `run-devenv-shell [--instance 0|wsN|N] [cmd...]`: bash in target instance. (`--instance` flag not yet renamed to `--ws`.)
- `start-devenv` / `log-devenv` / `drop-devenv`: legacy paths around ws0 + shared infra. `drop-devenv` never removes volumes.
`exporter/scripts/run` and `wait-and-start.sh` source `backend/scripts/_env` then `_env.local` if present.

8
.serena/memories/mcp/core.md
View File

@ -85,3 +85,11 @@ From the `mcp/` directory, run
* `pnpm run build` to test the build of all packages
* `pnpm run fmt` to apply the auto-formatter
## Devenv plugin/server wiring
In the normal Penpot devenv MCP path, the browser plugin does not discover or route through Postgres. The frontend provides the plugin extension API with `mcp.getServerUrl()`, currently derived from `frontend/src/app/config.cljs` as `penpotMcpServerURI` if set, otherwise `<public-uri>/mcp/ws`. The MCP plugin opens a direct WebSocket to that URL and appends the current MCP access token as a query parameter.
The live plugin connection registry is in-memory inside each MCP server process (`PluginBridge.connectedClients` / `clientsByToken`). The database only stores MCP access tokens and profile props such as `mcp-enabled`; it does not manage which plugin is connected to which MCP server.
For parallel devenvs, prefer same-origin MCP routing: each Penpot instance should expose `/mcp/ws` through its own nginx/Caddy path to the MCP server running inside the same main container. Keep container-internal ports fixed (MCP defaults `4401/4402/4403`, backend/exporter/frontend defaults, etc.) and only offset host-side published ports per instance. If internal ports are offset, hardcoded local proxy config such as `docker/devenv/files/nginx.conf` will misroute unless templated too.

33
.serena/memories/prod-infra/core.md Normal file
View File

@ -0,0 +1,33 @@
# Production infrastructure (services Penpot depends on)
Backend (`app.config`, `PENPOT_*` env vars) is parameterized; deployments choose providers.
## Services
- **PostgreSQL**: durable store. Profiles, teams, files, sessions, audit, `storage_object` metadata, the `task` queue, `scheduled_task` cron registry, migrations. File-data also lives here when the file-data backend is `legacy-db`/`db`. One shared DB across all backends.
- **Redis (Valkey-compatible)**: per-backend message bus and cache. Concrete uses: msgbus Pub/Sub for collaborative-editing broadcasts and team/profile-org notifications fired by RPC handlers (`app.rpc.notifications`, `files_update`, `teams`, `websocket`); file-summary cache gated by `enable-redis-cache`; rate-limit counters; and the dispatcher→runner work hand-off list `penpot.worker.queue:<tenant>:<queue>`. `PENPOT_REDIS_URI`.
- **Object storage**: backends `:s3` and `:fs`. S3 in prod; devenv uses MinIO. Holds uploaded media, file-data when the file-data backend is `storage`, exports. Backend-side details (resolve, dedup, bucket set, file-data backends): `mem:backend/http-storage-filedata-subtleties`.
- **SMTP mailer**: invitations, password resets, email verification (sent via the `:sendmail` worker task).
- **LDAP** (optional auth provider): helpers in `app.auth.*`, gated by `enable-login-with-ldap`.
## Task queue and worker model
Async tasks are enqueued via `wrk/submit!` (`app.worker`), which inserts a row into the shared Postgres `task` table tagged with `queue = "<tenant>:<queue-name>"`. Submission is **fire-and-forget** — RPC handlers never poll, never wait, and workers never publish to msgbus. The only completion signal is the `task` row's `status` / `completed_at` columns, which nothing in `rpc/` reads. Soft-delete RPCs return immediately after marking the top-level row, leaving the cascade and reaping to workers.
Workers run on backends with `enable-backend-worker` in `PENPOT_FLAGS`. Each worker-enabled backend has a `dispatcher` (polls `task` with `FOR UPDATE SKIP LOCKED`, marks status='scheduled', RPUSHes claimed task IDs into **its own** Redis list) and one or more `runner`s per queue (BLPOP from that same local list, execute, update the Postgres row). The Redis hand-off list is purely intra-backend — cross-backend coordination happens at the Postgres row level.
## Cross-backend safety
Postgres row locking is the only correctness primitive: `task` claims via `FOR UPDATE SKIP LOCKED`, cron firing via `FOR UPDATE SKIP LOCKED` on the `scheduled_task` row, plus task-handler-internal locks (e.g. `file_gc_scheduler` locks candidate file rows). This makes the work-claim path safe across any number of worker-enabled backends.
Two known race patterns survive multi-backend operation:
- **Cron dedup is best-effort.** The lock on `scheduled_task` is released when the task body finishes. If two backends' cron timers fire for the same scheduled instant with a gap larger than the task body's runtime, both execute it. Penpot's cron entries are idempotent (`session-gc`, `objects-gc`, `storage-gc-*`, `tasks-gc`, `upload-session-gc`, `file-gc-scheduler`); the exceptions are `:telemetry` (would double-report) and `:audit-log-archive` (depends on archive target idempotency).
- **`wrk/submit! ::dedupe true`** does a non-atomic `DELETE` then `INSERT`. Concurrent cross-backend submits can both bypass the `DELETE` (each sees the other's uncommitted insert as absent) and end up with duplicate `'new'` rows. Each row claims and runs once independently, so the underlying work is fine; the "at most one pending" guarantee weakens.
Penpot in production lives with both: horizontal-scale deployments accept "exactly-once" as "essentially-once for idempotent operations." Devenv parallel instances handle it by running workers only on ws0 (see `mem:devenv/core`).
## See also
- Devenv composition and the ws0-only worker placement: `mem:devenv/core`.
- Storage backend resolution, dedup, file-data lifecycle: `mem:backend/http-storage-filedata-subtleties`.

36
backend/scripts/_env
View File

@ -8,8 +8,18 @@ export PENPOT_SECRET_KEY=super-secret-devenv-key
# DEPRECATED: only used for subscriptions
export PENPOT_MANAGEMENT_API_KEY=super-secret-management-api-key
export PENPOT_HOST=devenv
export PENPOT_PUBLIC_URI=https://localhost:3449
# Runtime config that varies per devenv instance (PENPOT_HOST, PENPOT_PUBLIC_URI,
# PENPOT_DATABASE_*, PENPOT_REDIS_URI, PENPOT_OBJECTS_STORAGE_*, AWS_*) is owned by
# docker/devenv/defaults.env and injected via the main service's env block.
# Background worker flag is per-instance. Defaults to enabled (ws0); ws1+
# overlays set PENPOT_BACKEND_WORKER=false so scheduled and async tasks only
# run on ws0, keeping notification Pub/Sub bound to a single Valkey. See
# mem:devenv/core for the rationale.
__worker_flag=""
if [[ "${PENPOT_BACKEND_WORKER:-true}" == "true" ]]; then
__worker_flag="enable-backend-worker"
fi
export PENPOT_FLAGS="\
$PENPOT_FLAGS \
@ -20,7 +30,7 @@ export PENPOT_FLAGS="\
disable-login-with-github \
disable-login-with-gitlab \
disable-telemetry \
enable-backend-worker \
$__worker_flag \
enable-backend-asserts \
disable-feature-fdata-pointer-map \
enable-feature-fdata-objects-map \
@ -60,12 +70,6 @@ export PENPOT_HTTP_SERVER_MAX_MULTIPART_BODY_SIZE=314572800
export PENPOT_USER_FEEDBACK_DESTINATION="support@example.com"
export AWS_ACCESS_KEY_ID=penpot-devenv
export AWS_SECRET_ACCESS_KEY=penpot-devenv
export PENPOT_OBJECTS_STORAGE_BACKEND=s3
export PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=http://minio:9000
export PENPOT_OBJECTS_STORAGE_S3_BUCKET=penpot
export PENPOT_NITRATE_BACKEND_URI=http://localhost:3000/admin-console
export JAVA_OPTS="\
@ -84,14 +88,14 @@ export JAVA_OPTS="\
--enable-native-access=ALL-UNNAMED";
function setup_minio() {
# Initialize MINIO config
mc alias set penpot-s3/ http://minio:9000 minioadmin minioadmin -q
mc admin user add penpot-s3 penpot-devenv penpot-devenv -q
mc admin user info penpot-s3 penpot-devenv |grep -F -q "readwrite"
if [ "$?" = "1" ]; then
mc admin policy attach penpot-s3 readwrite --user=penpot-devenv -q
if [ "${PENPOT_OBJECTS_STORAGE_BACKEND}" != "s3" ]; then
return 0
fi
mc mb penpot-s3/penpot -p -q
# Shared MinIO user/policy provisioning is handled by docker-compose.infra.yml.
# Per process startup only ensures that the configured bucket exists.
mc alias set penpot-s3/ "${PENPOT_OBJECTS_STORAGE_S3_ENDPOINT}" minioadmin minioadmin -q
mc mb "penpot-s3/${PENPOT_OBJECTS_STORAGE_S3_BUCKET}" -p -q
}

69
docker/devenv/defaults.env Normal file
View File

@ -0,0 +1,69 @@
# Single source of truth for instance-specific devenv configuration.
# Loaded by docker compose via --env-file and also sourced by manage.sh
# (see manage.sh). This is the ws0 baseline; for ws1+ manage.sh injects the
# per-instance values as environment variables (see instance-env-overrides),
# which override these via Compose's shell-over-env-file precedence. Variables
# not overridden fall back to the values here.
#
# Backend runtime defaults that compose does not care about live in
# backend/scripts/_env.
# Container names and volume names. Volumes are pinned by explicit name
# (rather than relying on COMPOSE_PROJECT_NAME prefixing) so the physical
# volumes survive project renames without a data migration. ws0 reuses the
# pre-Stage-2 physical volume names (penpotdev_*).
PENPOT_MAIN_CONTAINER_NAME=penpot-devenv-ws0-main
PENPOT_VALKEY_CONTAINER_NAME=penpot-devenv-ws0-valkey
PENPOT_VALKEY_HOSTNAME=penpot-devenv-ws0-valkey
PENPOT_POSTGRES_DATA_VOLUME=penpotdev_postgres_data_pg16
PENPOT_MINIO_DATA_VOLUME=penpotdev_minio_data
PENPOT_USER_DATA_VOLUME=penpotdev_user_data
PENPOT_VALKEY_DATA_VOLUME=penpotdev_valkey_data
# Backend runtime config (passed to the container env block). PENPOT_REDIS_URI
# is set explicitly per instance to match the per-instance Valkey container
# name; ws1+ overlays override this.
PENPOT_HOST=devenv
PENPOT_PUBLIC_URI=https://localhost:3449
PENPOT_DATABASE_URI=postgresql://postgres/penpot
PENPOT_DATABASE_USERNAME=penpot
PENPOT_DATABASE_PASSWORD=penpot
PENPOT_DATABASE_MAX_POOL_SIZE=20
PENPOT_REDIS_URI=redis://penpot-devenv-ws0-valkey/0
# Object storage (MinIO user/policy are provisioned by the infra compose file).
PENPOT_OBJECTS_STORAGE_BACKEND=s3
PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=http://minio:9000
PENPOT_OBJECTS_STORAGE_S3_BUCKET=penpot
AWS_ACCESS_KEY_ID=penpot-devenv
AWS_SECRET_ACCESS_KEY=penpot-devenv
# Published host ports. Only ports that need to be reachable from outside the
# container are exposed; everything else (frontend dev server, backend API,
# storybook, exporter, REPLs, plugins, MCP inspector/websocket, aux) is
# accessed in-process or through the same-origin Caddy/nginx proxy at
# PENPOT_PUBLIC_HTTP_PORT. Container-internal ports remain fixed; per-instance
# overlays may offset these host-side values.
PENPOT_PUBLIC_HTTP_PORT=3449
PENPOT_MCP_SERVER_PORT=4401
PENPOT_MCP_REPL_PORT=4403
SHADOW_SERVER_URL=wss://localhost:3449
# Serena (agentic devenv). These are the published host ports for ws0; ws1+
# offset them by 10000*N. The container-internal ports (Serena MCP 14281,
# dashboard 24282) are fixed by Serena and mapped to these in compose.
SERENA_EXTERNAL_PORT=14181
SERENA_DASHBOARD_EXTERNAL_PORT=14182
# Backend worker (scheduled + async tasks). ws0 only; per-instance overlays
# for ws1+ override this to false. See mem:devenv/core.
PENPOT_BACKEND_WORKER=true
# Tmux session inside the main container.
PENPOT_TMUX_ATTACH=true
# Base directory holding non-main workspace clones (one subdir per wsN, N>=1).
# Consumed by manage.sh only. Default lives in manage.sh ($HOME expansion is
# not applied to values in this file). Export PENPOT_WORKSPACES_DIR to
# override.

99
docker/devenv/docker-compose.infra.yml Normal file
View File

@ -0,0 +1,99 @@
networks:
default:
name: penpot_shared
external: true
volumes:
postgres_data_pg16:
name: ${PENPOT_POSTGRES_DATA_VOLUME}
minio_data:
name: ${PENPOT_MINIO_DATA_VOLUME}
services:
minio:
image: "minio/minio:RELEASE.2025-04-03T14-56-28Z"
command: minio server /mnt/data --console-address ":9001"
volumes:
- "minio_data:/mnt/data"
environment:
- MINIO_ROOT_USER=minioadmin
- MINIO_ROOT_PASSWORD=minioadmin
networks:
default:
aliases:
- minio
minio-setup:
image: "minio/mc:latest"
depends_on:
- minio
entrypoint: ["/bin/sh", "-c"]
command:
- |
attempts=0
until mc alias set penpot-s3 http://minio:9000 minioadmin minioadmin -q; do
attempts=$$((attempts + 1))
if [ "$$attempts" -ge 30 ]; then
echo "minio-setup: gave up waiting for MinIO after $$attempts attempts" >&2
exit 1
fi
sleep 1
done
mc admin user info penpot-s3 penpot-devenv >/dev/null 2>&1 || mc admin user add penpot-s3 penpot-devenv penpot-devenv -q
mc admin policy attach penpot-s3 readwrite --user=penpot-devenv -q
networks:
default:
postgres:
image: postgres:16.8
command: postgres -c config_file=/etc/postgresql.conf
restart: always
stop_signal: SIGINT
environment:
- POSTGRES_INITDB_ARGS=--data-checksums
- POSTGRES_DB=penpot
- POSTGRES_USER=penpot
- POSTGRES_PASSWORD=penpot
volumes:
- ./files/postgresql.conf:/etc/postgresql.conf:z
- ./files/postgresql_init.sql:/docker-entrypoint-initdb.d/init.sql:z
- postgres_data_pg16:/var/lib/postgresql/data
networks:
default:
aliases:
- postgres
mailer:
image: sj26/mailcatcher:latest
restart: always
expose:
- '1025'
ports:
- "1080:1080"
networks:
default:
aliases:
- mailer
# https://github.com/rroemhild/docker-test-openldap
ldap:
image: rroemhild/test-openldap:2.1
expose:
- '10389'
- '10636'
ports:
- "10389:10389"
- "10636:10636"
ulimits:
nofile:
soft: 1024
hard: 1024
networks:
default:
aliases:
- ldap

106
docker/devenv/docker-compose.main.yml Normal file
View File

@ -0,0 +1,106 @@
networks:
default:
name: penpot_shared
external: true
volumes:
user_data:
name: ${PENPOT_USER_DATA_VOLUME}
valkey_data:
name: ${PENPOT_VALKEY_DATA_VOLUME}
services:
main:
privileged: true
image: "penpotapp/devenv:latest"
build:
context: "."
container_name: "${PENPOT_MAIN_CONTAINER_NAME}"
stop_signal: SIGINT
# postgres / minio / minio-setup live in the penpotdev-infra compose
# project and cannot be referenced via depends_on across projects.
# manage.sh waits for infra readiness before bringing main up.
depends_on:
redis:
condition: service_started
volumes:
- "user_data:/home/penpot/"
- "${PENPOT_SOURCE_PATH}:/home/penpot/penpot:z"
ports:
# Host ports are instance-specific; container ports stay fixed.
- ${PENPOT_PUBLIC_HTTP_PORT}:3449
- ${PENPOT_PUBLIC_HTTP_PORT}:3449/udp
# MCP
- ${PENPOT_MCP_SERVER_PORT}:4401
- ${PENPOT_MCP_REPL_PORT}:4403
# Serena MCP server (agentic mode only). Internal ports fixed by Serena.
- ${SERENA_EXTERNAL_PORT}:14281
- ${SERENA_DASHBOARD_EXTERNAL_PORT}:24282
environment:
- EXTERNAL_UID=${CURRENT_USER_ID}
# SMTP setup (shared infra service; identical across instances)
- PENPOT_SMTP_ENABLED=true
- PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
- PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
- PENPOT_SMTP_HOST=mailer
- PENPOT_SMTP_PORT=1025
- PENPOT_SMTP_USERNAME=
- PENPOT_SMTP_PASSWORD=
- PENPOT_SMTP_SSL=false
- PENPOT_SMTP_TLS=false
# LDAP setup (shared infra service; identical across instances)
- PENPOT_LDAP_HOST=ldap
- PENPOT_LDAP_PORT=10389
- PENPOT_LDAP_SSL=false
- PENPOT_LDAP_STARTTLS=false
- PENPOT_LDAP_BASE_DN=ou=people,dc=planetexpress,dc=com
- PENPOT_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
- PENPOT_LDAP_BIND_PASSWORD=GoodNewsEveryone
- PENPOT_LDAP_ATTRS_USERNAME=uid
- PENPOT_LDAP_ATTRS_EMAIL=mail
- PENPOT_LDAP_ATTRS_FULLNAME=cn
- PENPOT_LDAP_ATTRS_PHOTO=jpegPhoto
# Per-instance runtime config. Defaults live in defaults.env.
- PENPOT_HOST=${PENPOT_HOST}
- PENPOT_PUBLIC_URI=${PENPOT_PUBLIC_URI}
- PENPOT_DATABASE_URI=${PENPOT_DATABASE_URI}
- PENPOT_DATABASE_USERNAME=${PENPOT_DATABASE_USERNAME}
- PENPOT_DATABASE_PASSWORD=${PENPOT_DATABASE_PASSWORD}
- PENPOT_DATABASE_MAX_POOL_SIZE=${PENPOT_DATABASE_MAX_POOL_SIZE}
- PENPOT_REDIS_URI=${PENPOT_REDIS_URI}
- PENPOT_OBJECTS_STORAGE_BACKEND=${PENPOT_OBJECTS_STORAGE_BACKEND}
- PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=${PENPOT_OBJECTS_STORAGE_S3_ENDPOINT}
- PENPOT_OBJECTS_STORAGE_S3_BUCKET=${PENPOT_OBJECTS_STORAGE_S3_BUCKET}
- AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
- AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
- PENPOT_BACKEND_WORKER=${PENPOT_BACKEND_WORKER}
- PENPOT_TMUX_ATTACH=${PENPOT_TMUX_ATTACH}
# Agentic devenv: set to a commit/tag to update Serena on startup,
# leave empty to skip update and use the version baked into the image.
- SERENA_UPDATE_VERSION=1.5.0
- SHADOW_SERVER_URL=${SHADOW_SERVER_URL}
networks:
- default
redis:
image: valkey/valkey:8.1
hostname: "${PENPOT_VALKEY_HOSTNAME}"
container_name: "${PENPOT_VALKEY_CONTAINER_NAME}"
restart: always
command: valkey-server --save 120 1 --loglevel warning
volumes:
- "valkey_data:/data"
networks:
- default

180
docker/devenv/docker-compose.yaml
View File

@ -1,180 +0,0 @@
networks:
default:
driver: bridge
ipam:
config:
- subnet: 172.177.9.0/24
volumes:
postgres_data_pg16:
user_data:
minio_data:
valkey_data:
services:
main:
privileged: true
image: "penpotapp/devenv:latest"
build:
context: "."
container_name: "penpot-devenv-main"
stop_signal: SIGINT
depends_on:
- postgres
- redis
# - keycloak
volumes:
- "user_data:/home/penpot/"
- "${PWD}:/home/penpot/penpot:z"
ports:
- 3447:3447
- 3448:3448
- 3449:3449
- 3449:3449/udp
- 3450:3450
- 6006:6006
- 6060:6060
- 6061:6061
- 6062:6062
- 6063:6063
- 6064:6064
- 9000:9000
- 9001:9001
- 9090:9090
- 9091:9091
# MCP
- 4400:4400
- 4401:4401
- 4402:4402
- 4403:4403
# Plugins
- 4200:4200
- 4201:4201
- 4202:4202
# Serena MCP server (agentic mode only)
- ${SERENA_EXTERNAL_PORT:-14281}:14281
- ${SERENA_DASHBOARD_EXTERNAL_PORT:-14282}:24282
environment:
- EXTERNAL_UID=${CURRENT_USER_ID}
# SMTP setup
- PENPOT_SMTP_ENABLED=true
- PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
- PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
- PENPOT_SMTP_HOST=mailer
- PENPOT_SMTP_PORT=1025
- PENPOT_SMTP_USERNAME=
- PENPOT_SMTP_PASSWORD=
- PENPOT_SMTP_SSL=false
- PENPOT_SMTP_TLS=false
# LDAP setup
- PENPOT_LDAP_HOST=ldap
- PENPOT_LDAP_PORT=10389
- PENPOT_LDAP_SSL=false
- PENPOT_LDAP_STARTTLS=false
- PENPOT_LDAP_BASE_DN=ou=people,dc=planetexpress,dc=com
- PENPOT_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
- PENPOT_LDAP_BIND_PASSWORD=GoodNewsEveryone
- PENPOT_LDAP_ATTRS_USERNAME=uid
- PENPOT_LDAP_ATTRS_EMAIL=mail
- PENPOT_LDAP_ATTRS_FULLNAME=cn
- PENPOT_LDAP_ATTRS_PHOTO=jpegPhoto
# agentic devenv
# Serena update: set to a commit/tag to update Serena on startup, leave empty to skip update and use the version in the image
- SERENA_UPDATE_VERSION=1.5.0
networks:
default:
aliases:
- main
minio:
image: "minio/minio:RELEASE.2025-04-03T14-56-28Z"
command: minio server /mnt/data --console-address ":9001"
volumes:
- "minio_data:/mnt/data"
environment:
- MINIO_ROOT_USER=minioadmin
- MINIO_ROOT_PASSWORD=minioadmin
networks:
default:
aliases:
- minio
postgres:
image: postgres:16.8
command: postgres -c config_file=/etc/postgresql.conf
restart: always
stop_signal: SIGINT
environment:
- POSTGRES_INITDB_ARGS=--data-checksums
- POSTGRES_DB=penpot
- POSTGRES_USER=penpot
- POSTGRES_PASSWORD=penpot
volumes:
- ./files/postgresql.conf:/etc/postgresql.conf:z
- ./files/postgresql_init.sql:/docker-entrypoint-initdb.d/init.sql:z
- postgres_data_pg16:/var/lib/postgresql/data
networks:
default:
aliases:
- postgres
redis:
image: valkey/valkey:8.1
hostname: "penpot-devenv-valkey"
container_name: "penpot-devenv-valkey"
restart: always
command: valkey-server --save 120 1 --loglevel warning
volumes:
- "valkey_data:/data"
networks:
default:
aliases:
- redis
mailer:
image: sj26/mailcatcher:latest
restart: always
expose:
- '1025'
ports:
- "1080:1080"
networks:
default:
aliases:
- mailer
# https://github.com/rroemhild/docker-test-openldap
ldap:
image: rroemhild/test-openldap:2.1
expose:
- '10389'
- '10636'
ports:
- "10389:10389"
- "10636:10636"
ulimits:
nofile:
soft: 1024
hard: 1024
networks:
default:
aliases:
- ldap

4
docker/devenv/files/Caddyfile
View File

@ -15,7 +15,3 @@ localhost:3449 {
# }
reverse_proxy localhost:4449
}
http://penpot-devenv-main:3450 {
reverse_proxy localhost:4449
}

7
docker/devenv/files/nginx.conf
View File

@ -136,6 +136,13 @@ http {
proxy_http_version 1.1;
}
location /api/remote-relay {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_pass http://127.0.0.1:3448;
proxy_http_version 1.1;
}
location /mcp/ws {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';

75
docker/devenv/files/start-tmux.sh
View File

@ -6,6 +6,23 @@ cd ~;
source ~/.bashrc
PENPOT_TMUX_SESSION="penpot"
PENPOT_TMUX_ATTACH="${PENPOT_TMUX_ATTACH:-true}"
function attach_or_exit() {
if [ "$PENPOT_TMUX_ATTACH" = "true" ]; then
exec tmux -2 attach-session -t "$PENPOT_TMUX_SESSION"
fi
echo "[start-tmux.sh] tmux session '$PENPOT_TMUX_SESSION' is running detached"
exit 0
}
if tmux has-session -t "$PENPOT_TMUX_SESSION" 2>/dev/null; then
echo "[start-tmux.sh] Reusing existing tmux session '$PENPOT_TMUX_SESSION'"
attach_or_exit
fi
echo "[start-tmux.sh] Installing node dependencies"
pushd ~/penpot/frontend/
./scripts/setup;
@ -14,32 +31,32 @@ pushd ~/penpot/exporter/
./scripts/setup;
popd
tmux -2 new-session -d -s penpot
tmux -2 new-session -d -s "$PENPOT_TMUX_SESSION"
tmux rename-window -t penpot:0 'frontend watch'
tmux select-window -t penpot:0
tmux send-keys -t penpot 'cd penpot/frontend' enter C-l
tmux send-keys -t penpot './scripts/watch app' enter
tmux rename-window -t "$PENPOT_TMUX_SESSION:0" 'frontend watch'
tmux select-window -t "$PENPOT_TMUX_SESSION:0"
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/frontend' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch app' enter
tmux new-window -t penpot:1 -n 'frontend storybook'
tmux select-window -t penpot:1
tmux send-keys -t penpot 'cd penpot/frontend' enter C-l
tmux send-keys -t penpot './scripts/watch storybook' enter
tmux new-window -t "$PENPOT_TMUX_SESSION:1" -n 'frontend storybook'
tmux select-window -t "$PENPOT_TMUX_SESSION:1"
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/frontend' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch storybook' enter
tmux new-window -t penpot:2 -n 'exporter'
tmux select-window -t penpot:2
tmux send-keys -t penpot 'cd penpot/exporter' enter C-l
tmux send-keys -t penpot 'rm -f target/app.js*' enter C-l
tmux send-keys -t penpot './scripts/watch' enter
tmux new-window -t "$PENPOT_TMUX_SESSION:2" -n 'exporter'
tmux select-window -t "$PENPOT_TMUX_SESSION:2"
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/exporter' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'rm -f target/app.js*' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch' enter
tmux split-window -v
tmux send-keys -t penpot 'cd penpot/exporter' enter C-l
tmux send-keys -t penpot './scripts/wait-and-start.sh' enter
tmux split-window -v -t "$PENPOT_TMUX_SESSION"
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/exporter' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/wait-and-start.sh' enter
tmux new-window -t penpot:3 -n 'backend'
tmux select-window -t penpot:3
tmux send-keys -t penpot 'cd penpot/backend' enter C-l
tmux send-keys -t penpot './scripts/start-dev' enter
tmux new-window -t "$PENPOT_TMUX_SESSION:3" -n 'backend'
tmux select-window -t "$PENPOT_TMUX_SESSION:3"
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/backend' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/start-dev' enter
if echo "$PENPOT_FLAGS" | grep -q "enable-mcp"; then
pushd ~/penpot/mcp/
@ -47,10 +64,10 @@ if echo "$PENPOT_FLAGS" | grep -q "enable-mcp"; then
pnpm run build;
popd
tmux new-window -t penpot:4 -n 'mcp'
tmux select-window -t penpot:4
tmux send-keys -t penpot 'cd penpot/mcp' enter C-l
tmux send-keys -t penpot './scripts/start-mcp-devenv' enter
tmux new-window -t "$PENPOT_TMUX_SESSION:4" -n 'mcp'
tmux select-window -t "$PENPOT_TMUX_SESSION:4"
tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/mcp' enter C-l
tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/start-mcp-devenv' enter
fi
if [ "${SERENA_ENABLED:-false}" = "true" ]; then
@ -58,9 +75,9 @@ if [ "${SERENA_ENABLED:-false}" = "true" ]; then
# update Serena (use sudo since the initial Serena installation is global; see Dockerfile)
sudo -E uv tool install -p 3.13 serena-agent@${SERENA_UPDATE_VERSION} --prerelease=allow
fi
tmux new-window -t penpot:5 -n 'serena'
tmux select-window -t penpot:5
tmux send-keys -t penpot "serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context ${SERENA_CONTEXT} --host 0.0.0.0" enter
tmux new-window -t "$PENPOT_TMUX_SESSION:5" -n 'serena'
tmux select-window -t "$PENPOT_TMUX_SESSION:5"
tmux send-keys -t "$PENPOT_TMUX_SESSION" "serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context ${SERENA_CONTEXT} --host 0.0.0.0" enter
fi
tmux -2 attach-session -t penpot
attach_or_exit

341
docs/technical-guide/developer/agentic-devenv.md
View File

@ -5,18 +5,73 @@ desc: Dive into agentic Penpot development.
# Agentic Development Environment
The agentic DevEnv is an extension of the standard DevEnv
(the [general DevEnv instructions](/technical-guide/developer/devenv/) apply),
which is optimised for AI agent-based development,
adding additional tools and processes that support agentic automation.
The agentic DevEnv is an extension of the standard DevEnv (the
[general DevEnv instructions](/technical-guide/developer/devenv/) apply),
optimised for AI agent-based development. It adds MCP servers (Penpot,
Serena, Playwright) and supports a launcher that wires them into your AI client.
The general workflow is as follows:
Two things to know up front:
1. Start the agentic DevEnv.
2. Start a debugging-enabled browser and open Penpot, using a Penpot user with
the remote MCP integration enabled.
3. Use an AI client (MCP client) which is connected to a suite of MCP servers
to solve development tasks.
- **Parallel workspaces are first-class.** Run several devenv instances side
by side - one per AI agent if you like - each with its own source-tree
clone, ports, and tmux session. Pass `--ws N` to target one.
- **Your existing AI-client config is preserved.** The launcher loads a
per-workspace MCP config on top of your global one.
## Quick Start
1. **Bring up one or more workspaces**[^cfg]:
```bash
./manage.sh run-devenv-agentic # ws0 (the live repo)
./manage.sh run-devenv-agentic --ws 1 # ws1 (sibling clone)
```
Add `--ws 2`, `--ws 3`, … for more parallel workspaces.
2. **Launch a browser with remote debugging enabled:**
For example, with Chrome:
```bash
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
```
3. **Open Penpot in that browser:**
- ws0: <https://localhost:3449>
- ws1: <https://localhost:13449>
- etc. (ports are offset by `10000 × N` for `wsN`)
On first login per account, open settings → Integrations and toggle
"MCP Server" on. The agentic DevEnv runs the MCP server in single-user
mode - the key and proxied URL shown in the UI are not needed.
4. **Launch your AI client** against the workspace you want it to drive:
```bash
./manage.sh start-coding-agent claude # ws0
./manage.sh start-coding-agent claude --ws 1 # ws1
```
Supported clients: `claude` | `opencode` | `vscode` | `codex`.
5. **Attach to the tmux session** for the workspace (optional):
```bash
./manage.sh attach-devenv # ws0
./manage.sh attach-devenv --ws 1 # ws1
```
6. **Shut down workspaces** with `./manage.sh stop-devenv`, either one by one or all at once.
You cannot shut down `ws0` if any other workspace is still running, since it's the worker-bearer.
Shared infrastructure will be cleaned up when the last workspace is stopped.
Optional: watch Serena's activity in its dashboard
(<http://localhost:14182> for ws0, <http://localhost:24182> for ws1, etc.).
[^cfg]: One-time, if you don't already have it: set
`penpotFlags = "enable-mcp"` in `frontend/resources/public/js/config.js`
(gitignored; create if missing).
## Capabilities
@ -32,7 +87,6 @@ with a comprehensive toolbox for Penpot development:
* **Serena MCP Server** provides code intelligence tools with support for Clojure and TypeScript.
Its memory system is used to organise project knowledge in a context-efficient manner.
* **Playwright MCP Server** provides tools for browser remote control.
* (optional) **GitHub MCP Server** provides tools for interacting with GitHub (issue, PRs, etc.)
Equipped with the tools provided by these MCP servers, the agent can fully close the development loop,
i.e. it can ...
@ -47,122 +101,247 @@ i.e. it can ...
* test the changes in the live Penpot instance, and
* create commits and PRs resolving the issue.
## Configuring and Starting the Agentic DevEnv
## The flow in detail
**First-Time Setup: Building the Image.** If you are starting the agentic DevEnv for the first time, you need to build
the updated docker image, adding support for agentic tools:
### First-time setup
```bash
./manage.sh build-devenv --local
```
**Enable the Penpot MCP Connection in the Frontend.**
The agentic DevEnv relies on a connection between the Penpot frontend and the Penpot MCP server
being established automatically.
Edit the file `frontend/resources/public/js/config.js`,
creating it if it does not exist, and make sure the `penpotFlags` variable contains the
`enable-mcp` flag.
**The MCP frontend flag.** Edit `frontend/resources/public/js/config.js`
(create it if missing) and ensure `penpotFlags` contains `enable-mcp`:
```javascript
var penpotFlags = "enable-mcp";
```
**Running the DevEnv in Agentic Mode.** Start the DevEnv in agentic mode with:
The file is gitignored and lives in the live repo only. On every
`run-devenv-agentic` call it is read directly for ws0; for wsN (N ≥ 1) it is
copied into the workspace clone on the **initial** sync only - subsequent
`--sync` passes leave the workspace's copy alone so per-workspace
customisations survive. `run-devenv-agentic` refuses to start if the file is
missing.
```bash
./manage.sh run-devenv-agentic
```
## Opening Penpot with Remote Debugging & MCP Enabled
**Enable Remote Debugging in Your Browser.**
Penpot needs to be opened in a browser that has remote debugging enabled.
In Chromium-based browsers (such as Google Chrome, Opera, Vivaldi, etc.),
this can be achieved by launching the browser with the `--remote-debugging-port` argument.
For most newer browsers, you will also need to specify a user data directory,
as using debugging with your regular browser profile is disallowed for security reasons.
**Browser remote debugging.** The Playwright MCP server drives a real
browser instance over the Chrome DevTools protocol. To enable it, launch a
Chromium-based browser (Chrome, Vivaldi, Opera, …) with the
`--remote-debugging-port` flag and a separate user-data directory:
```bash
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
```
This enables the Playwright MCP server to connect to the browser and control it.
Verify that debugging was enabled correctly by navigating to `http://127.0.0.1:9222/json/version`.
If you change the port, adjust the MCP server configuration accordingly (see below).
Note: For security reasons, you should not enable remote debugging with a profile
that you use for regular browsing activities.
Verify it works by visiting `http://127.0.0.1:9222/json/version`. If you
change the port, update the Playwright MCP entry in `.devenv/shared/*.json`
accordingly. For security reasons, do not enable remote debugging on the
profile you use for regular browsing.
**Open Penpot with the MCP Integration Enabled.**
The Penpot instance in the DevEnv can be accessed at [https://localhost:3449](https://localhost:3449).
Once logged in, navigate to your account settings, click on "Integrations" in the sidebar, and enable the "MCP Server" toggle.
Note: You do not need to use the generated key (or the provided URL), as the MCP server in the agentic DevEnv is running in single-user mode and does not require authentication.
**Enable the MCP integration in Penpot.** The Penpot UI has a per-account
MCP toggle. After logging into your Penpot instance at
[https://localhost:3449](https://localhost:3449), open account settings,
click "Integrations" in the sidebar, and enable the "MCP Server" toggle.
The agentic DevEnv runs the MCP server in single-user mode, so the
generated key and proxied URL printed in the UI are *not* needed - only the
toggle itself matters.
## Configuring Your AI Client
**(Optional) custom devenv image.** Only needed if you want to modify the
devenv image itself (add a tool, change a base layer):
Your AI client needs to be configured to connect to the MCP servers that collectively provide the agent with the necessary tools for Penpot development.
```bash
./manage.sh build-devenv --local
```
Below, we exemplarily provide a JSON-based configuration snippet, using `mcp-remote` to wrap HTTP-based servers.
The default `run-devenv-agentic` flow pulls the published image
automatically, so regular users never run this.
Most clients using JSON-based configuration (e.g. Copilot, JetBrains AI Assistant, Claude Desktop, Antigravity)
will work when inserting the server entries below into the client's configuration file.
If your client uses a different configuration format, extract the relevant information (i.e. server URLs or launch commands)
and configure the servers appropriately, referring to the documentation of your client.
### Bringing up workspaces
```bash
./manage.sh run-devenv-agentic \
[--ws N] [--sync] [--serena-context CTX] \
[--git-user-name NAME] [--git-user-email EMAIL]
```
Brings one agentic instance up. Errors out if the target is already running.
`--ws N` (N ≥ 1) auto-starts ws0 first if it is not already up - ws0 is the
worker-bearer and must be running whenever any wsN is. Per-instance ports
are offset by `10000 × N` (ws1's MCP at `http://localhost:14401/mcp`, Serena
MCP at `http://localhost:24181`, Serena dashboard at
`http://localhost:24182`, etc.). `manage.sh` prints the full URL set on
every bring-up so you don't compute offsets by hand. See the
[Dev environment guide](./devenv.md) for the workspace lifecycle, `--sync`
semantics, and stop ordering.
**Git identity for agent commits.** Coding agents typically need to commit
inside the devenv, so `run-devenv-agentic` wires a Git identity into the
container's global config on every bring-up. By default it propagates the
host's effective `git config user.{name,email}` (local repo override wins
over `~/.gitconfig`, matching what `git commit` on the host would record).
Override with `--git-user-name "Full Name"` / `--git-user-email
you@example.com` when you want agent commits to carry an identity different
from your normal one. Without either source the script warns and proceeds;
commits inside the devenv will fail until you fix it. See the
[Dev environment guide](./devenv.md#git-identity-inside-the-container) for
the full mechanics.
> **Note:** the MCP and Serena tmux windows are only added when the tmux
> session is first created. If a workspace was already brought up with
> `./manage.sh run-devenv` (non-agentic), stop it before re-running
> agentically:
>
> ```bash
> ./manage.sh stop-devenv
> ./manage.sh run-devenv-agentic
> ```
### Launching an AI client
The agentic environment supports any AI client, one just needs to set the right MCP config,
see [manual configuration](#manual-ai-client-configuration) below. For some popular clients, the `manage.sh`
CLI offers direct support through the following mechanism:
Every `run-devenv-agentic` regenerates three MCP-client config files with
the workspace's ports baked in; Codex is wired up at launch instead (see
below):
| Client | File | Loaded how |
| ------ | ---- | ---------- |
| Claude Code | `<workspace>/.devenv/mcp/claude-code.json` | `--mcp-config <file>` flag |
| opencode | `<workspace>/.devenv/mcp/opencode.json` | `OPENCODE_CONFIG=<file>` env var |
| VS Code Copilot | `<workspace>/.vscode/mcp.json` | Auto-discovered when opening the workspace |
| Codex CLI | _(none written)_ | Injected as `-c mcp_servers.…` overrides by `start-coding-agent codex` |
The files are committed templates + an `envsubst` pass; see
[`.devenv/README.md`](../../../.devenv/README.md) for the full layout.
`./manage.sh start-coding-agent <client> [--ws N] [...passthrough]`
launches the chosen client against one workspace, `cd`'ing into the right
directory and refusing to launch if the instance is not running:
```bash
./manage.sh start-coding-agent claude # ws0
./manage.sh start-coding-agent opencode --ws 1 # ws1
./manage.sh start-coding-agent vscode # opens VS Code on ws0
./manage.sh start-coding-agent codex --ws 2 # ws2
```
A given AI client session drives **exactly one workspace**, so running N
parallel workspaces typically means running N AI client sessions, each
pointed at a different workspace's ports.
What each launcher does:
* **Claude Code** is started with `--mcp-config .devenv/mcp/claude-code.json`,
which is **additive** - your existing global Claude Code MCP entries stay
available alongside the three entries we ship (Penpot MCP, Serena MCP,
Playwright). To shadow one of our entries with a private one, install it
under Claude Code's local scope (`claude mcp add --scope local …`); local
wins over `--mcp-config`.
* **opencode** is started with `OPENCODE_CONFIG=.devenv/mcp/opencode.json`.
opencode's precedence chain is *global → `OPENCODE_CONFIG` → project*, so
the file we generate **overrides** entries with the same name in your
global config. To override our entries in turn, drop a personal
`opencode.json` at the repo root - it's gitignored on purpose.
* **VS Code Copilot** - `code "$workspace"` opens VS Code on the workspace.
Copilot loads both your user-profile MCP config and the workspace's
`.vscode/mcp.json`. That workspace file is **deep-merged** rather than
overwritten: on ws0 (where it *is* the live repo's own file) any servers you
added survive, and only our three (Penpot MCP, Serena MCP, Playwright) are
rewritten to the current ports; on ws1+ it is created from scratch. To shadow
one of ours, add a same-named entry in your user profile - it wins.
* **Codex CLI** - `codex` is exec'd from the workspace dir with our servers
passed as `-c mcp_servers.<name>....` overrides built from the committed
templates. **Nothing is written to `.codex/config.toml`**, so your own
project- or user-level Codex config is left untouched (and no "trusted
project" prompt is involved for our servers). Because `-c` is Codex's
highest-precedence layer, our entries win over a same-named server in your
config; to override one, append your own `-c` after the client name
(`... start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`) - the
later `-c` wins.
## Manual AI-client configuration
The `start-coding-agent` launcher covers Claude Code, opencode, VS Code
Copilot, and the Codex CLI. For any other client (JetBrains AI Assistant,
Claude Desktop, Antigravity, …), or if you prefer to wire things up
yourself, configure the MCP servers in your client's native format using
the URLs below.
The Penpot and Serena URLs for the workspace you want to target are printed
by `manage.sh` every time it brings an instance up; copy them straight from
that output. The mechanical rule is `port = base + 10000 × N` for `wsN`,
with bases `4401` (Penpot MCP) and `14181` (Serena MCP). Playwright is not
workspace-scoped - it connects to your local browser, so the same entry
works for every client.
### Project-level MCP config files (Claude Code, opencode - manual path)
If you'd rather not go through the launcher, both Claude Code and opencode
support project-level MCP config files that **merge with** the developer's
global config:
* **Claude Code** reads `.mcp.json` at the project root. Local scope
(`claude mcp add --scope local …`) overrides project scope.
* **opencode** reads `opencode.json` at the project root (or any ancestor
Git directory). Configs are merged in the order *global → `OPENCODE_CONFIG`
→ project*.
The schemas differ between the two, so a workspace supporting both ships
both files. For multi-workspace work, edit the port numbers in each
workspace's copy once to match its offset.
### Example configuration
Below is a JSON-based configuration snippet in Claude Code's `mcpServers`
schema, targeting `ws0` (main), using `mcp-remote` to wrap HTTP-based
servers. To target a different workspace, substitute the Penpot MCP and
Serena MCP URLs with the ones for that workspace.
For clients using a different configuration format, extract the relevant
information (server URLs or launch commands) and configure the servers
appropriately, referring to your client's documentation.
```json
{
"mcpServers": {
"penpot": {
"penpot-ws0": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:4401/mcp", "--allow-http" ]
},
"serena-devenv": {
"serena-ws0-devenv": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:14281/mcp", "--allow-http"]
"args": ["-y", "mcp-remote", "http://localhost:14181/mcp", "--allow-http"]
},
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "TODO_your_token"
}
}
}
}
```
**Penpot MCP Server**
* The URL above connects directly to the server in the DevEnv, which runs in single-user mode.
You do not need to use the proxied URL or the user token that is provided by the Penpot UI.
* The URL above connects directly to the server in the DevEnv, which runs
in single-user mode. You do not need to use the proxied URL or the user
token that is provided by the Penpot UI.
**Serena MCP Server**
* You can access Serena's dashboard at [http://localhost:14282](http://localhost:14282)
**GitHub MCP Server**
* The use of this MCP server is optional. (Direct shell access to GitHub CLI can be used alternatively.)
* You need to provide a personal access token (PAT) with appropriate permissions:
* Create a token in your GitHub account settings [here](https://github.com/settings/personal-access-tokens).
* Choose the right resource owner: As a member of the `penpot` organisation, be sure to create a token where the resource owner is the organisation.
Otherwise, you will not be able to create pull requests or issues in the `penpot/penpot` repository.
* Grant the necessary permissions, e.g. read and write access to issues and pull requests.
* The matching Serena dashboard lives on the next port (`14182` for ws0,
`24182` for ws1, …) and is also printed by `manage.sh` on startup.
## Working on Development Tasks
After having made the configuration changes, restart your AI client.
All four MCP servers should now be running and accessible to your client.
After having made the configuration changes, restart your AI client. The
configured MCP servers should now be running and accessible to your client.
The agent's entrypoint for development is an activation of the `penpot` project with Serena.
Start by instructing your agent as follows,
The agent's entrypoint for development is an activation of the `penpot`
project with Serena. Start by instructing your agent as follows,
> Activate project penpot.
and it should retrieve fundamental project information,
expecting further instructions on what to do.
and it should retrieve fundamental project information, expecting further
instructions on what to do.
**Always start your first prompt with these activation instructions**, as this bootstraps the agent's context.
**Always start your first prompt with these activation instructions**, as
this bootstraps the agent's context.
### Checking MCP Server Operability

150
docs/technical-guide/developer/devenv.md
View File

@ -45,13 +45,153 @@ This is an incomplete list of devenv related subcommands found on
manage.sh script:
```bash
./manage.sh build-devenv-local # builds the local devenv docker image (called by run-devenv automatically when needed)
./manage.sh start-devenv # starts background running containers
./manage.sh run-devenv # enters to new tmux session inside of one of the running containers
./manage.sh stop-devenv # stops background running containers
./manage.sh drop-devenv # removes all the containers, volumes and networks used by the devenv
./manage.sh build-devenv --local # builds the local devenv docker image
./manage.sh start-devenv # brings up the shared infra + ws0 in background
./manage.sh run-devenv # ws0 with non-agentic tmux, attached (legacy alias)
./manage.sh run-devenv-agentic # one agentic instance; --ws to target ws1+; see below
./manage.sh attach-devenv # re-attaches to the tmux session of a running instance
./manage.sh stop-devenv # stops one instance (or --all); infra stops with the last
./manage.sh drop-devenv # removes containers (data volumes preserved)
```
### Parallel workspaces
The devenv runs as separate compose projects: shared infra (`penpotdev-infra`:
Postgres, MinIO, mailer, LDAP) plus one `penpotdev-wsN` project per runtime
instance. `ws0` (a.k.a. `main`) binds the live repo; `ws1+` bind clones the
developer maintains explicitly under `${PENPOT_WORKSPACES_DIR}/wsN/`
(default `~/.penpot/penpot_workspaces/`).
Each call to `run-devenv-agentic` brings up one instance, and ws0 is always
running whenever any ws1+ is — `--ws N` (N≥1) auto-starts ws0 first if it
isn't already up:
```bash
./manage.sh run-devenv-agentic # main (ws0)
./manage.sh run-devenv-agentic --ws 1 # ws0 if needed, then ws1
./manage.sh run-devenv-agentic --ws 2 --sync # ws2, re-seeding from the live repo
```
Starting an instance that is already running is an error. `--sync` is only
valid for `ws1+`; on ws0 it errors out. When a `ws1+` workspace directory
does not exist yet, the first start syncs it implicitly from the live repo.
Otherwise the workspace contents are left untouched unless `--sync` is passed
again. Live-repo Git in a fragile state (rebase / merge / cherry-pick /
`index.lock`) blocks all syncs.
`frontend/resources/public/js/config.js` (which is gitignored and configures
the frontend's MCP flag) is copied into each workspace on its initial sync
only. After that the developer maintains it in each workspace; subsequent
`--sync` runs leave the workspace copy alone.
Stopping mirrors the start invariant — ws0 is the last to stop, and shared
infra stops with it:
```bash
./manage.sh stop-devenv --ws 1 # stops ws1; ws0 + infra stay up
./manage.sh stop-devenv # stops ws0 + infra; errors if ws1+ still running
./manage.sh stop-devenv --all # stops every ws1+ first, then ws0 + infra
```
Host ports are offset by `10000 × N`:
| Service | ws0 | ws1 | ws2 |
|---|---|---|---|
| Penpot UI (HTTPS) | `https://localhost:3449` | `https://localhost:13449` | `https://localhost:23449` |
| MCP HTTP stream | `http://localhost:4401/mcp` | `http://localhost:14401/mcp` | `http://localhost:24401/mcp` |
| Serena MCP | `http://localhost:14181` | `http://localhost:24181` | `http://localhost:34181` |
Container-internal ports stay fixed. Target a specific instance with
`--ws N` on `attach-devenv`, `run-devenv-agentic`, `stop-devenv`,
`start-coding-agent`, `run-devenv-shell`, and `isolated-shell`. `--ws`
accepts a **non-negative integer only** — `--ws main` or `--ws ws1` is
rejected, keeping the flag shape uniform across commands. `run-devenv` is
ws0-only and takes no workspace flag. `run-devenv-agentic` also accepts
`--serena-context CTX` and `--git-user-name NAME` / `--git-user-email
EMAIL` (see below).
Configuration lives in one tracked file, `docker/devenv/defaults.env` (the
ws0 baseline); `ws1+` values (offset ports, `wsN` container/volume names) are
derived and injected automatically, so there is no per-instance file to edit.
### Git identity inside the container
`run-devenv-agentic` wires a Git author identity into the container's
**global** git config (`git config --global user.{name,email}`) so commits
made from inside the devenv carry a real author/committer. Without this,
the container would commit as the unconfigured `penpot@<container>`
fallback — usable but useless for review.
The values come from `--git-user-name NAME` / `--git-user-email EMAIL`
when passed, or from your host's effective `git config user.{name,email}`
otherwise. "Effective" here means the values plain `git config user.X`
returns at the working directory `manage.sh` is invoked from — local
(`<repo>/.git/config`) overrides global (`~/.gitconfig`), matching what
`git commit` on the host would record. If neither is available the script
prints a warning and continues — commits will fail inside the container
until you set an identity. The values are applied every time
`run-devenv-agentic` brings an instance up (idempotent), so re-running
with different flags is the way to change the in-container identity.
### Shared state and workers
All instances share one Penpot database and one MinIO bucket; users, teams,
files, and MCP tokens are visible from every instance. Per-instance Valkey
keeps msgbus Pub/Sub channels (collab broadcasts, team-org notifications,
file-summary cache, rate-limit counters) isolated.
Background workers (`enable-backend-worker`) run only on ws0 — ws1+ overlays
disable it. ws1+ RPC handlers still enqueue tasks into the shared Postgres
`task` table; ws0's dispatcher claims them via `FOR UPDATE SKIP LOCKED` and
runs them against the shared DB and MinIO. The "ws0 always up when ws1+ is
up" invariant exists for this reason: it keeps a single worker-bearer and
avoids the multi-instance cron-dedup race (the lock on `scheduled_task` is
released when the task body finishes, so two cron timers firing the same
scheduled instant with a gap larger than the body's runtime can both
execute it).
### Upgrading from a pre-parallel devenv
The devenv compose configuration has been split into two files and reorganized
into separate compose projects per runtime instance:
- `docker/devenv/docker-compose.infra.yml` (Postgres, MinIO, mailer, LDAP)
runs under the compose project `penpotdev-infra`.
- `docker/devenv/docker-compose.main.yml` (one main container + its Valkey)
runs once per runtime instance under `penpotdev-ws0`, `penpotdev-ws1`, ….
- Both projects join the external Docker network `penpot_shared`, created
idempotently by `manage.sh`.
- Configuration lives in `docker/devenv/defaults.env` (the ws0 baseline);
ws1+ overrides are computed and injected at compose time.
If you had the devenv running on the previous single-project (`penpotdev`)
layout, leftover containers and the auto-generated `penpotdev_default`
network must be removed before bringing the new ws0 instance up. The named
data volumes (`penpotdev_postgres_data_pg16`, `penpotdev_minio_data`,
`penpotdev_user_data`, `penpotdev_valkey_data`) are pinned by explicit
`name:` entries in the new compose files and are preserved through the
transition — your Postgres DB, MinIO objects, and home cache survive.
One-time cleanup, then bring up ws0:
```bash
# Stop and remove the old single-project containers (data volumes stay).
docker stop penpot-devenv-main penpot-devenv-valkey 2>/dev/null
docker rm penpotdev-postgres-1 penpotdev-minio-1 penpotdev-minio-setup-1 \
penpotdev-mailer-1 penpotdev-ldap-1 \
penpot-devenv-main penpot-devenv-valkey 2>/dev/null
# Remove the orphaned auto-generated network.
docker network rm penpotdev_default 2>/dev/null
# Bring up infra + ws0 under the new project layout.
./manage.sh run-devenv-agentic
```
After the cleanup, normal `./manage.sh start-devenv` / `run-devenv` /
`run-devenv-agentic` commands work against the new layout. The legacy
`penpotdev` compose project is no longer used.
Having the container running and tmux opened inside the container,
you are free to execute commands and open as many shells as you want.

4
exporter/scripts/run
View File

@ -3,4 +3,8 @@
SCRIPT_DIR=$(dirname $0);
source $SCRIPT_DIR/../../backend/scripts/_env;
if [ -f $SCRIPT_DIR/../../backend/scripts/_env.local ]; then
source $SCRIPT_DIR/../../backend/scripts/_env.local;
fi
exec node target/app.js

4
exporter/scripts/wait-and-start.sh
View File

@ -3,6 +3,10 @@
SCRIPT_DIR=$(dirname $0);
source $SCRIPT_DIR/../../backend/scripts/_env;
if [ -f $SCRIPT_DIR/../../backend/scripts/_env.local ]; then
source $SCRIPT_DIR/../../backend/scripts/_env.local;
fi
bb -i '(babashka.wait/wait-for-port "localhost" 9630)';
bb -i '(babashka.wait/wait-for-path "target/app.js")';
sleep 2;

18
frontend/shadow-cljs.edn
View File

@ -9,8 +9,14 @@
{:target :esm
:output-dir "resources/public/js/"
:asset-path "/js"
:devtools {:watch-dir "resources/public"
:reload-strategy :full}
;; :devtools is dev-only, so it lives under :dev -- shadow merges that map
;; for `watch`/`compile` but not `release`, keeping :devtools-url out of
;; release entirely (shadow spec-checks it as non-empty-string? whenever the
;; key is present, even in release). In the devenv SHADOW_SERVER_URL is
;; always set per workspace (see defaults.env / manage.sh).
:dev {:devtools {:watch-dir "resources/public"
:reload-strategy :full
:devtools-url #shadow/env ["SHADOW_SERVER_URL" :default ""]}}
:build-options {:manifest-name "manifest.json"}
:modules
{:shared
@ -86,9 +92,11 @@
{:target :browser
:output-dir "resources/public/js/worker/"
:asset-path "/js/worker"
:devtools {:browser-inject :main
:watch-dir "resources/public"
:reload-strategy :full}
;; Dev-only; see the :main build above for why :devtools lives under :dev.
:dev {:devtools {:devtools-url #shadow/env ["SHADOW_SERVER_URL" :default ""]
:browser-inject :main
:watch-dir "resources/public"
:reload-strategy :full}}
:build-options {:manifest-name "manifest.json"}
:modules
{:main

1071
manage.sh
View File

File diff suppressed because it is too large Load Diff