Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(console): run the managed local stack on the switch-core in your checkout (#258)

Louis Amaudruzc08ab866e337
diff --git a/console/AGENTS.md b/console/AGENTS.md
index ee686385c..8572cece6 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -672,6 +672,18 @@ pnpm run test
duration. Nothing is downloaded or installed, and the harness cannot activate in
a packaged build. Example:
`SWITCHDASH_FAKE_UPDATE=available pnpm run dev`.
+- The managed local Switch server in dev: a dev build launched from a Switch
+ checkout shows a **"Build switch-core from this checkout"** toggle on the local
+ server's page. With it on, every start layers a generated build override on the
+ bundled compose file and runs `up -d --build`, so `switch`, `gateway` and
+ `setup` are built from the working tree and tagged `dev-checkout` instead of
+ pulling the pinned GHCR images. The choice persists in
+ `local-switch-server/checkout-build.json` under user-data and applies from the
+ next start. The compose file stays the bundled pinned one — re-sync it
+ (`pnpm run sync:compose`) if the checkout's own standalone compose has moved
+ on. Because the tag is not a semver, the downgrade guard cannot run against a
+ checkout build; it is skipped with a warning rather than silently.
+ See `src/main/core/managed-switch-server/checkout-build.ts`.
- Deeplinks in dev: `pnpm run dev` does **not** claim the `switchdash://` OS URL
scheme by default — doing so hijacks the handler from the installed app and the
registration outlives the dev process (on macOS it sticks in Launch Services),
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/checkout-build.test.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/checkout-build.test.ts
new file mode 100644
index 000000000..47c3ab95f
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/checkout-build.test.ts
@@ -0,0 +1,81 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+ checkoutBuildOverrideYaml,
+ findCoreCheckout,
+ isCheckoutBuildEnabled,
+ setCheckoutBuildEnabled,
+} from './checkout-build';
+
+async function fakeCheckout(): Promise<string> {
+ const root = await mkdtemp(join(tmpdir(), 'switch-checkout-'));
+ for (const marker of [
+ 'core/pyproject.toml',
+ 'deploy/shared_resources/images/Dockerfile.switch',
+ 'deploy/shared_resources/images/Dockerfile.gateway',
+ 'deploy/shared_resources/images/Dockerfile.setup',
+ ]) {
+ const path = join(root, marker);
+ await mkdir(dirname(path), { recursive: true });
+ await writeFile(path, '');
+ }
+ return root;
+}
+
+describe('findCoreCheckout', () => {
+ it('finds the checkout root from a directory inside it', async () => {
+ const root = await fakeCheckout();
+ const nested = join(root, 'console', 'apps', 'switch-console-desktop');
+ await mkdir(nested, { recursive: true });
+
+ expect(findCoreCheckout(nested)).toBe(root);
+ });
+
+ /** A packaged install is not in a source tree, and half a tree cannot be
+ * built — offering the option there would fail at `docker build`. */
+ it('answers null when no ancestor carries all the build inputs', async () => {
+ const root = await mkdtemp(join(tmpdir(), 'not-switch-'));
+ await mkdir(join(root, 'core'), { recursive: true });
+ await writeFile(join(root, 'core', 'pyproject.toml'), '');
+
+ expect(findCoreCheckout(root)).toBeNull();
+ });
+});
+
+describe('checkoutBuildOverrideYaml', () => {
+ /** The override is written into the stack's working dir under user-data, so a
+ * relative context would resolve there rather than in the checkout. */
+ it('gives every built service an absolute context in the checkout', () => {
+ const yaml = checkoutBuildOverrideYaml('/src/switch');
+
+ for (const service of ['switch', 'gateway', 'setup']) {
+ expect(yaml).toContain(` ${service}:`);
+ }
+ expect(yaml).toContain('context: "/src/switch"');
+ expect(yaml).not.toContain('context: .');
+ expect(yaml).toContain('dockerfile: deploy/shared_resources/images/Dockerfile.switch');
+ });
+
+ it('quotes a path with spaces so compose reads one value', () => {
+ expect(checkoutBuildOverrideYaml('/Users/dev/my switch')).toContain(
+ 'context: "/Users/dev/my switch"'
+ );
+ });
+});
+
+describe('the persisted choice', () => {
+ it('round-trips, and is off until it has been turned on', async () => {
+ const stateDir = await mkdtemp(join(tmpdir(), 'switch-state-'));
+ const host = { stateDir };
+
+ expect(await isCheckoutBuildEnabled(host)).toBe(false);
+
+ await setCheckoutBuildEnabled(host, true);
+ expect(await isCheckoutBuildEnabled(host)).toBe(true);
+
+ await setCheckoutBuildEnabled(host, false);
+ expect(await isCheckoutBuildEnabled(host)).toBe(false);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/checkout-build.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/checkout-build.ts
new file mode 100644
index 000000000..462885d19
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/checkout-build.ts
@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import type { ServerHost } from './host/types';
+
+/**
+ * Dev-only mode: run the managed local stack on the switch-core in the
+ * developer's own checkout instead of the released images this build pins.
+ *
+ * The released path pulls `switch-core:<COMPATIBLE_SWITCH_VERSION>` and friends
+ * from GHCR. Here the same compose file is layered with a build override — the
+ * same one `just standalone-up` uses — so compose builds `switch`, `gateway`
+ * and `setup` from the working tree and tags them under a version of their own.
+ *
+ * The compose file itself is still the bundled pinned one — only the images
+ * change. A checkout whose own `deploy/local/standalone-docker-compose.yml` has
+ * moved on (a new service, a new env var) needs the bundled copy re-synced
+ * (`pnpm run sync:compose`) before this mode reflects it.
+ *
+ * It stays a developer tool: {@link findCoreCheckout} only answers when the app
+ * is running from a source tree that actually contains the Dockerfiles, and the
+ * caller gates it on `import.meta.env.DEV`.
+ */
+
+/** Files that identify a Switch checkout root — the compose build context and
+ * the Dockerfiles the override names. All must be present, so a half-matching
+ * ancestor directory cannot be mistaken for the repo. */
+const CHECKOUT_MARKERS = [
+ 'core/pyproject.toml',
+ 'deploy/shared_resources/images/Dockerfile.switch',
+ 'deploy/shared_resources/images/Dockerfile.gateway',
+ 'deploy/shared_resources/images/Dockerfile.setup',
+];
+
+/** Whether `dir` is the root of a Switch checkout the stack can be built from. */
+export function isCoreCheckout(dir: string): boolean {
+ return CHECKOUT_MARKERS.every((marker) => existsSync(join(dir, marker)));
+}
+
+/**
+ * The Switch checkout the running app was launched from, or null when it was
+ * not launched from one (a packaged install, or a source tree that has been
+ * moved away from the repo).
+ *
+ * Walks up from `startDir` — in `electron-vite dev` the main process runs with
+ * the desktop app's directory as its cwd, which is inside the repo.
+ */
+export function findCoreCheckout(startDir: string = process.cwd()): string | null {
+ let dir = startDir;
+ const { root } = parse(dir);
+ for (;;) {
+ if (isCoreCheckout(dir)) return dir;
+ if (dir === root) return null;
+ dir = dirname(dir);
+ }
+}
+
+/**
+ * The compose override that re-adds the `build:` blocks the published compose
+ * file drops, mirroring `deploy/local/standalone-docker-compose.build.yml`.
+ *
+ * The build context is absolute rather than `.`: compose resolves a relative
+ * context against the directory of the file that declares it, and this file is
+ * written into the stack's working dir under user-data, not into the checkout.
+ */
+export function checkoutBuildOverrideYaml(checkoutRoot: string): string {
+ const service = (name: string, dockerfile: string) =>
+ [
+ ` ${name}:`,
+ ' build:',
+ ` context: ${JSON.stringify(checkoutRoot)}`,
+ ` dockerfile: deploy/shared_resources/images/${dockerfile}`,
+ ].join('\n');
+ return [
+ '# Generated by Switch Console — do not edit by hand.',
+ '# Dev-only build override: builds the stack images from a local checkout',
+ `# (${checkoutRoot}) instead of pulling the pinned released images.`,
+ 'services:',
+ service('switch', 'Dockerfile.switch'),
+ service('gateway', 'Dockerfile.gateway'),
+ service('setup', 'Dockerfile.setup'),
+ '',
+ ].join('\n');
+}
+
+/** Reading the persisted choice only needs the state directory, not a live
+ * host — the same narrowing `ports.ts` makes. */
+type HostStateDir = Pick<ServerHost, 'stateDir'>;
+
+function choiceFilePath(host: HostStateDir): string {
+ return join(host.stateDir, 'checkout-build.json');
+}
+
+/** Whether the developer has turned checkout builds on for this stack. Off
+ * unless the file says otherwise, so an unreadable or absent choice can only
+ * fall back to the released images. */
+export async function isCheckoutBuildEnabled(host: HostStateDir): Promise<boolean> {
+ try {
+ const parsed: unknown = JSON.parse(await readFile(choiceFilePath(host), 'utf8'));
+ return (parsed as { enabled?: unknown } | null)?.enabled === true;
+ } catch {
+ return false;
+ }
+}
+
+/** Persist the choice next to the stack's other per-machine metadata. */
+export async function setCheckoutBuildEnabled(host: HostStateDir, enabled: boolean): Promise<void> {
+ await mkdir(dirname(choiceFilePath(host)), { recursive: true });
+ await writeFile(choiceFilePath(host), JSON.stringify({ enabled }, null, 2), 'utf8');
+}
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.test.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.test.ts
index 83a29fea0..9f4a875b4 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.test.ts
@@ -26,7 +26,7 @@ describe('composeUp', () => {
it('asks for plain progress before the subcommand, where compose accepts it', async () => {
const { host, streamCommand } = hostSpy();
- await composeUp(host, () => {});
+ await composeUp(host, () => {}, false);
const args = streamCommand.mock.calls[0]![1];
const progressAt = args.indexOf('--progress');
@@ -39,8 +39,36 @@ describe('composeUp', () => {
it('still brings the stack up detached', async () => {
const { host, streamCommand } = hostSpy();
- await composeUp(host, () => {});
+ await composeUp(host, () => {}, false);
expect(streamCommand.mock.calls[0]![1]).toEqual(expect.arrayContaining(['up', '-d']));
});
+
+ /** The dev-only checkout build layers the build override on top of the
+ * pinned compose file and asks compose to build; without `--build` an
+ * already-built image is reused and the working tree's changes never land. */
+ it('layers the build override and builds when running from a checkout', async () => {
+ const { host, streamCommand } = hostSpy();
+
+ await composeUp(host, () => {}, true);
+
+ const args = streamCommand.mock.calls[0]![1];
+
+ expect(args).toEqual(expect.arrayContaining(['-f', 'standalone-docker-compose.build.yml']));
+ expect(args.indexOf('standalone-docker-compose.yml')).toBeLessThan(
+ args.indexOf('standalone-docker-compose.build.yml')
+ );
+ expect(args).toEqual(expect.arrayContaining(['up', '-d', '--build']));
+ });
+
+ it('does not build or override on the released path', async () => {
+ const { host, streamCommand } = hostSpy();
+
+ await composeUp(host, () => {}, false);
+
+ const args = streamCommand.mock.calls[0]![1];
+
+ expect(args).not.toContain('standalone-docker-compose.build.yml');
+ expect(args).not.toContain('--build');
+ });
});
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.ts
index 7d5401432..ba77a6ab3 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/compose.ts
@@ -1,5 +1,10 @@
import { log } from '@main/lib/logger';
-import { COMPOSE_FILE_NAME, ENV_FILE_NAME, LOCAL_SERVER_PROFILES } from './constants';
+import {
+ BUILD_OVERRIDE_FILE_NAME,
+ COMPOSE_FILE_NAME,
+ ENV_FILE_NAME,
+ LOCAL_SERVER_PROFILES,
+} from './constants';
import type { ServerHost } from './host/types';
/** Pulls can take minutes on a cold machine; give compose a generous ceiling. */
@@ -11,12 +16,13 @@ function profileArgs(): string[] {
/** Base args that scope every invocation to the managed project + env file.
* Relative file names resolve against the host working dir (the ctx root). */
-function baseArgs(host: ServerHost, globalFlags: string[]): string[] {
+function baseArgs(host: ServerHost, globalFlags: string[], extraFiles: string[] = []): string[] {
return [
'compose',
...globalFlags,
'-f',
COMPOSE_FILE_NAME,
+ ...extraFiles.flatMap((file) => ['-f', file]),
'--env-file',
ENV_FILE_NAME,
'--project-name',
@@ -44,16 +50,33 @@ async function runCompose(host: ServerHost, args: string[], timeout: number): Pr
* Bring the stack up in the background (`up -d`), streaming each line of output
* to `onLog` so the UI can show a live tail during the (slow) image pull.
* Assumes the compose file and `.env` are written and GHCR login has run.
+ *
+ * `fromCheckout` layers the dev-only build override on top of the compose file
+ * and adds `--build`, so the stack's images come from the developer's working
+ * tree instead of the registry (see checkout-build.ts). The override must
+ * already be written to the host working dir.
*/
-export function composeUp(host: ServerHost, onLog: (line: string) => void): Promise<void> {
- log.info(`local-switch-server: docker compose up (${host.label})`);
+export function composeUp(
+ host: ServerHost,
+ onLog: (line: string) => void,
+ fromCheckout: boolean
+): Promise<void> {
+ log.info(
+ `local-switch-server: docker compose up (${host.label})${fromCheckout ? ' from local checkout' : ''}`
+ );
// Compose already falls back to plain, line-per-event output when it is not
// attached to a TTY, which is how we always run it — so this pins the
// behaviour we depend on rather than changing it. `--progress` belongs to
// `compose`, not to `up`; after the subcommand it exits with "unknown flag".
+ const overrides = fromCheckout ? [BUILD_OVERRIDE_FILE_NAME] : [];
return host.streamCommand(
host.dockerBin,
- [...baseArgs(host, ['--progress', 'plain']), 'up', '-d'],
+ [
+ ...baseArgs(host, ['--progress', 'plain'], overrides),
+ 'up',
+ '-d',
+ ...(fromCheckout ? ['--build'] : []),
+ ],
onLog,
{ timeoutMs: COMPOSE_TIMEOUT_MS }
);
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/constants.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/constants.ts
index 66fa07210..a4fa4d984 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/constants.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/constants.ts
@@ -35,6 +35,10 @@ export const REMOTE_SERVER_PROJECT_NAME =
export const COMPOSE_FILE_NAME = 'standalone-docker-compose.yml';
export const ENV_FILE_NAME = '.env';
+/** File name of the dev-only build override layered on top of the compose file
+ * when the stack is built from a local checkout (see checkout-build.ts). */
+export const BUILD_OVERRIDE_FILE_NAME = 'standalone-docker-compose.build.yml';
+
/** Display name of the auto-registered server record. */
export const LOCAL_SERVER_NAME = 'Local Switch server';
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/controller.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/controller.ts
index d66cd53c2..dfd411d1f 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/controller.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/controller.ts
@@ -16,4 +16,9 @@ export const localSwitchServerController = createRPCController({
stop: (): Promise<void> => localServerService.stop(),
reset: (): Promise<void> => localServerService.reset(),
+
+ /** Dev-only: build the stack's images from the local Switch checkout on the
+ * next start, instead of pulling this build's pinned images. */
+ setCheckoutBuild: (enabled: boolean): Promise<void> =>
+ localServerService.setCheckoutBuild(enabled),
});
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts
index 107909c89..c82a8f66a 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/local-server-service.ts
@@ -4,6 +4,8 @@ import { events } from '@main/lib/events';
import { log } from '@main/lib/logger';
import { COMPATIBLE_SWITCH_VERSION } from '@shared/app-identity';
import {
+ CHECKOUT_IMAGE_TAG,
+ type CheckoutBuild,
type DockerAvailability,
type LocalServerStatus,
type StartLocalServerResult,
@@ -13,6 +15,11 @@ import {
localServerLogChannel,
localServerStatusChannel,
} from '@shared/events/localSwitchServerEvents';
+import {
+ findCoreCheckout,
+ isCheckoutBuildEnabled,
+ setCheckoutBuildEnabled,
+} from './checkout-build';
import { isStackRunning } from './compose';
import { LOCAL_SERVER_NAME } from './constants';
import { readVersionStatus } from './deployed-version';
@@ -37,6 +44,7 @@ class LocalServerService {
version: COMPATIBLE_SWITCH_VERSION,
deployedVersion: null,
drift: null,
+ checkoutBuild: null,
message: null,
error: null,
};
@@ -57,6 +65,47 @@ class LocalServerService {
events.emit(localServerStatusChannel, this.status);
}
+ /**
+ * The dev-only checkout-build option for this machine, or null when it is not
+ * on offer: a released build, or a dev build that was not launched from a
+ * Switch checkout (so there are no Dockerfiles to build from).
+ */
+ private async readCheckoutBuild(host: ServerHost): Promise<CheckoutBuild | null> {
+ if (!import.meta.env.DEV) return null;
+ const root = findCoreCheckout();
+ if (!root) return null;
+ return { root, enabled: await isCheckoutBuildEnabled(host) };
+ }
+
+ /** The checkout the next start should build from, or null to pull the pinned
+ * released images. */
+ private checkoutRootForStart(): string | null {
+ const checkout = this.status.checkoutBuild;
+ return checkout?.enabled ? checkout.root : null;
+ }
+
+ /**
+ * Turn building from the local checkout on or off. Dev-only, and only when a
+ * checkout was found: anything else is a bug in the caller rather than a
+ * state to absorb quietly. Takes effect on the next start — the running
+ * containers are whatever the last start built or pulled.
+ */
+ async setCheckoutBuild(enabled: boolean): Promise<void> {
+ const checkout = this.status.checkoutBuild;
+ if (!checkout) {
+ throw new Error(
+ 'Building from a local checkout is only available in a dev build launched from a Switch checkout.'
+ );
+ }
+ const host: ServerHost = new LocalServerHost();
+ try {
+ await setCheckoutBuildEnabled(host, enabled);
+ this.setStatus({ checkoutBuild: { ...checkout, enabled } });
+ } finally {
+ host.dispose();
+ }
+ }
+
/** Reconcile status at boot so a stack that survived the last quit shows as
* running without the user re-starting it, and so an app update that moved
* the switch-core pin underneath it surfaces as drift instead of leaving the
@@ -68,12 +117,19 @@ class LocalServerService {
async initialize(): Promise<void> {
const host: ServerHost = new LocalServerHost();
try {
+ this.setStatus({ checkoutBuild: await this.readCheckoutBuild(host) });
const managed = await getManagedServer();
if (!managed) return;
if (await isStackRunning(host)) {
this.setStatus({ phase: 'running', serverId: managed.id, message: null, error: null });
}
- this.setStatus(await readVersionStatus(host, COMPATIBLE_SWITCH_VERSION));
+ const version = await readVersionStatus(host, COMPATIBLE_SWITCH_VERSION);
+ // A checkout build is deliberately not a comparable version, so the pin
+ // comparison has nothing to say about it — the UI reports it as a
+ // checkout build instead of as unexplained drift.
+ this.setStatus(
+ version.deployedVersion === CHECKOUT_IMAGE_TAG ? { ...version, drift: null } : version
+ );
} catch (error) {
log.warn('local-switch-server: boot status reconcile failed', { error });
} finally {
@@ -88,6 +144,7 @@ class LocalServerService {
this.busy = true;
this.startAbort = new AbortController();
const host: ServerHost = new LocalServerHost();
+ const checkoutRoot = this.checkoutRootForStart();
try {
this.setStatus({ phase: 'starting', error: null, message: 'Checking Docker…' });
const result = await startStack({
@@ -97,6 +154,7 @@ class LocalServerService {
onMessage: (message) => this.setStatus({ message }),
onLog: (line) => events.emit(localServerLogChannel, { line }),
signal: this.startAbort.signal,
+ checkoutRoot,
});
if (result.kind === 'docker-unavailable') {
this.setStatus({ phase: 'error', error: result.detail });
@@ -118,7 +176,7 @@ class LocalServerService {
serverId: result.serverId,
message: null,
error: null,
- deployedVersion: COMPATIBLE_SWITCH_VERSION,
+ deployedVersion: checkoutRoot !== null ? CHECKOUT_IMAGE_TAG : COMPATIBLE_SWITCH_VERSION,
drift: null,
});
}
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.test.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.test.ts
index ccec8bd0b..a2b45de87 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.test.ts
@@ -59,7 +59,9 @@ const { startStack } = await import('./pipeline');
const { ENV_FILE_NAME } = await import('./constants');
function options() {
- const writeFile = vi.fn(() => Promise.resolve());
+ const writeFile = vi.fn<(relPath: string, content: string, mode?: number) => Promise<void>>(() =>
+ Promise.resolve()
+ );
const host = {
label: 'this computer',
writeFile,
@@ -75,6 +77,7 @@ function options() {
onMessage: vi.fn(),
onLog: vi.fn(),
signal: new AbortController().signal,
+ checkoutRoot: null as string | null,
},
};
}
@@ -195,3 +198,46 @@ describe('startStack version guard', () => {
expect(writeFile).not.toHaveBeenCalled();
});
});
+
+describe('startStack checkout build', () => {
+ /** The whole point of the dev mode: the images must come from the working
+ * tree, and must not be tagged as if they were the pinned release. */
+ it('writes the build override, tags the images apart, and builds', async () => {
+ readDeployedVersionMock.mockResolvedValue({ kind: 'absent' });
+ const { opts, writeFile } = options();
+ opts.checkoutRoot = '/src/switch';
+
+ expect(await startStack(opts)).toEqual({ kind: 'started', serverId: 'srv-1' });
+
+ const override = writeFile.mock.calls.find(
+ ([name]) => name === 'standalone-docker-compose.build.yml'
+ );
+ expect(override?.[1]).toContain('/src/switch');
+ expect(composeUpMock).toHaveBeenCalledWith(expect.anything(), expect.any(Function), true);
+ });
+
+ it('skips the downgrade guard, saying so, rather than refusing the start', async () => {
+ readDeployedVersionMock.mockResolvedValue({
+ kind: 'deployed',
+ version: '0.12.0',
+ source: 'container',
+ });
+ const { opts } = options();
+ opts.checkoutRoot = '/src/switch';
+
+ expect(await startStack(opts)).toEqual({ kind: 'started', serverId: 'srv-1' });
+ expect(logWarn).toHaveBeenCalled();
+ });
+
+ it('leaves the released path unbuilt and without an override', async () => {
+ readDeployedVersionMock.mockResolvedValue({ kind: 'absent' });
+ const { opts, writeFile } = options();
+
+ await startStack(opts);
+
+ expect(
+ writeFile.mock.calls.some(([name]) => name === 'standalone-docker-compose.build.yml')
+ ).toBe(false);
+ expect(composeUpMock).toHaveBeenCalledWith(expect.anything(), expect.any(Function), false);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.ts
index e796683f1..e7492dbb9 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/pipeline.ts
@@ -3,11 +3,16 @@ import { passwordLogin } from '@main/core/switch-servers/auth';
import { ensureManagedServer, setActiveServerId } from '@main/core/switch-servers/servers-store';
import { log } from '@main/lib/logger';
import { COMPATIBLE_SWITCH_VERSION, RELEASE_REPO_OWNER } from '@shared/app-identity';
-import type { StartLocalServerResult } from '@shared/core/managed-switch-server/managed-switch-server';
+import {
+ CHECKOUT_IMAGE_TAG,
+ type StartLocalServerResult,
+} from '@shared/core/managed-switch-server/managed-switch-server';
import type { ManagedServerRef } from '@shared/core/switch-servers/switch-servers';
import { bundledComposeYaml } from './bundled-compose';
+import { checkoutBuildOverrideYaml } from './checkout-build';
import { composeDown, composeUp } from './compose';
import {
+ BUILD_OVERRIDE_FILE_NAME,
COMPOSE_FILE_NAME,
ENV_FILE_NAME,
GHCR_REGISTRY,
@@ -40,6 +45,9 @@ export type StartStackOptions = {
onLog: (line: string) => void;
/** Aborts an in-flight health wait (stop/cancel/quit). */
signal: AbortSignal;
+ /** Dev-only: root of the Switch checkout to build the stack's images from,
+ * instead of pulling this build's pinned images. Null is the released path. */
+ checkoutRoot: string | null;
};
/**
@@ -66,10 +74,26 @@ export type StartStackOptions = {
* log has to make that difference visible to whoever reads it afterwards.
*/
async function refuseDowngrade(
- host: ServerHost
+ host: ServerHost,
+ checkoutRoot: string | null
): Promise<{ kind: 'version-downgrade'; deployed: string; expected: string } | null> {
const deployed = await readDeployedVersion(host);
if (deployed.kind === 'absent') return null;
+ if (checkoutRoot !== null) {
+ log.warn(
+ `managed-switch-server: starting ${host.label} from the checkout at ${checkoutRoot} — ` +
+ `the downgrade check is skipped, because a working tree carries no comparable version. ` +
+ `If the stack's database is ahead of that checkout, this start may strand it.`
+ );
+ return null;
+ }
+ if (deployed.kind === 'deployed' && deployed.version === CHECKOUT_IMAGE_TAG) {
+ log.warn(
+ `managed-switch-server: ${host.label} currently runs a local checkout build, so the ` +
+ `downgrade check cannot run; pointing it back at pinned switch-core ${COMPATIBLE_SWITCH_VERSION}.`
+ );
+ return null;
+ }
if (deployed.kind === 'unreadable') {
log.warn(`managed-switch-server: starting ${host.label} without a deployed-version check`, {
reason: deployed.reason,
@@ -103,9 +127,13 @@ async function refuseDowngrade(
* from this build every time, so `compose up -d` on an already-running stack
* re-pulls the newly pinned tags and recreates only the changed containers,
* leaving the data volumes in place for switch-core to migrate forward.
+ *
+ * With `checkoutRoot` set (dev only) the images are built from that working
+ * tree on every start instead of pulled, and tagged {@link CHECKOUT_IMAGE_TAG}
+ * so nothing downstream mistakes them for a release.
*/
export async function startStack(opts: StartStackOptions): Promise<StartLocalServerResult> {
- const { host, ref, serverName, onMessage, onLog, signal } = opts;
+ const { host, ref, serverName, onMessage, onLog, signal, checkoutRoot } = opts;
const docker = await host.detectDocker();
if (!docker.available) {
@@ -113,11 +141,14 @@ export async function startStack(opts: StartStackOptions): Promise<StartLocalSer
}
onMessage('Checking the deployed version…');
- const downgrade = await refuseDowngrade(host);
+ const downgrade = await refuseDowngrade(host, checkoutRoot);
if (downgrade) return downgrade;
onMessage('Preparing configuration…');
await host.writeFile(COMPOSE_FILE_NAME, bundledComposeYaml());
+ if (checkoutRoot !== null) {
+ await host.writeFile(BUILD_OVERRIDE_FILE_NAME, checkoutBuildOverrideYaml(checkoutRoot));
+ }
const secrets = await loadOrCreateSecrets(host);
const ports = await resolvePorts(host);
const gatewayUrl = gatewayUrlFor(ports);
@@ -125,7 +156,7 @@ export async function startStack(opts: StartStackOptions): Promise<StartLocalSer
await host.writeFile(
ENV_FILE_NAME,
buildEnvFile({
- version: COMPATIBLE_SWITCH_VERSION,
+ version: checkoutRoot !== null ? CHECKOUT_IMAGE_TAG : COMPATIBLE_SWITCH_VERSION,
registry: GHCR_REGISTRY,
namespace: RELEASE_REPO_OWNER,
ports,
@@ -134,8 +165,12 @@ export async function startStack(opts: StartStackOptions): Promise<StartLocalSer
0o600
);
- onMessage('Starting containers (pulling images if needed)…');
- await composeUp(host, onLog);
+ onMessage(
+ checkoutRoot !== null
+ ? `Building images from ${checkoutRoot} and starting containers…`
+ : 'Starting containers (pulling images if needed)…'
+ );
+ await composeUp(host, onLog, checkoutRoot !== null);
// Make the published ports reachable from the desktop (no-op locally; a
// mirrored SSH forward remotely) BEFORE the health probe, so the probe takes
diff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts
index 966a35fdb..49a40631d 100644
--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts
+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/remote-server-service.ts
@@ -32,6 +32,9 @@ function initialStatus(sshHost: string): RemoteServerStatus {
version: COMPATIBLE_SWITCH_VERSION,
deployedVersion: null,
drift: null,
+ // A remote host builds nothing: its stack always runs the pinned released
+ // images, so the dev checkout option is not on offer there.
+ checkoutBuild: null,
message: null,
error: null,
};
@@ -168,6 +171,7 @@ class RemoteServerService {
onMessage: (message) => this.setStatus(sshHost, { message }),
onLog: (line) => events.emit(remoteServerLogChannel, { sshHost, line }),
signal: abort.signal,
+ checkoutRoot: null,
});
if (result.kind === 'docker-unavailable') {
this.setStatus(sshHost, { phase: 'error', error: result.detail });
diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/LocalServerControls.tsx b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/LocalServerControls.tsx
index 44cf62f54..4927682f1 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/LocalServerControls.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/LocalServerControls.tsx
@@ -3,6 +3,8 @@ import { observer } from 'mobx-react-lite';
import { useEffect, useState } from 'react';
import { Alert, AlertDescription, AlertTitle } from '@renderer/lib/ui/alert';
import { Spinner } from '@renderer/lib/ui/spinner';
+import { Switch } from '@renderer/lib/ui/switch';
+import { CHECKOUT_IMAGE_TAG } from '@shared/core/managed-switch-server/managed-switch-server';
import { localServerStore } from './local-server-store';
import { LogTail } from './log-tail';
import { phaseLabel, StackAction, StackSection, StackStatusRow } from './server-stack-section';
@@ -28,6 +30,13 @@ export const LocalServerControls = observer(function LocalServerControls() {
// A stack ahead of this build must not be started at all: doing so would point
// it at a core older than its database has migrated to (CHOO-1736).
const downgradeBlocked = store.drift?.direction === 'downgrade';
+ // Dev builds run from a Switch checkout only; null everywhere else.
+ const checkout = store.checkoutBuild;
+ const runsCheckoutBuild = store.status?.deployedVersion === CHECKOUT_IMAGE_TAG;
+ // The toggle applies from the next start on, so say so while the containers
+ // are still the ones the previous choice produced.
+ const restartToApply =
+ checkout !== null && store.isRunning && checkout.enabled !== runsCheckoutBuild;
return (
<StackSection>
@@ -35,7 +44,13 @@ export const LocalServerControls = observer(function LocalServerControls() {
title="Local server"
phase={store.phase}
summary={store.isRunning ? 'Running on this computer' : phaseLabel(store.phase)}
- versionDetail={runningVersion ? `switch-core ${runningVersion}` : null}
+ versionDetail={
+ runsCheckoutBuild && checkout
+ ? `switch-core built from ${checkout.root}`
+ : runningVersion
+ ? `switch-core ${runningVersion}`
+ : null
+ }
activity={
store.logs.length > 0 ? (
<button
@@ -99,6 +114,31 @@ export const LocalServerControls = observer(function LocalServerControls() {
</Alert>
)}
+ {/* Dev builds launched from a Switch checkout only — a released build
+ never has a source tree to build from, so the row is absent rather
+ than disabled. */}
+ {checkout && (
+ <div className="flex items-start justify-between gap-3 rounded-md border border-dashed border-border p-3">
+ <div className="min-w-0">
+ <p className="text-sm text-foreground">Build switch-core from this checkout</p>
+ <p className="mt-0.5 text-xs text-foreground-muted">
+ Dev builds only. Builds the switch, gateway and setup images from{' '}
+ <span className="font-mono break-all">{checkout.root}</span> on every start, instead
+ of pulling switch-core {store.status?.version}. They are tagged{' '}
+ <span className="font-mono">{CHECKOUT_IMAGE_TAG}</span> so they can't be mistaken
+ for a release.
+ {restartToApply && ' Restart the server to apply.'}
+ </p>
+ </div>
+ <Switch
+ checked={checkout.enabled}
+ disabled={transitioning}
+ onCheckedChange={(enabled) => void store.setCheckoutBuild(enabled)}
+ aria-label="Build switch-core from this checkout"
+ />
+ </div>
+ )}
+
{/* Behind the disclosure rather than shown the moment there is output:
the log is what you go looking for, not what the section is for. */}
{showActivity && store.logs.length > 0 && <LogTail lines={store.logs} placeholder={null} />}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/local-server-store.ts b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/local-server-store.ts
index ab0fb2a4c..53d622467 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/local-server-store.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/local-server-store.ts
@@ -3,6 +3,7 @@ import { agentsStore } from '@renderer/features/locations/stores/agents-store';
import { describeFailure } from '@renderer/lib/errors/describe-failure';
import { events, rpc } from '@renderer/lib/ipc';
import type {
+ CheckoutBuild,
DockerAvailability,
LocalServerStatus,
SwitchVersionDrift,
@@ -81,6 +82,13 @@ export class LocalServerStore {
return this.status?.drift ?? null;
}
+ /** Dev builds launched from a Switch checkout only: the checkout the stack's
+ * images can be built from, and whether that is on. Null everywhere else, and
+ * the controls hide the option when it is. */
+ get checkoutBuild(): CheckoutBuild | null {
+ return this.status?.checkoutBuild ?? null;
+ }
+
get isTransitioning(): boolean {
return this.busy || this.phase === 'starting' || this.phase === 'stopping';
}
@@ -209,6 +217,16 @@ export class LocalServerStore {
}
}
+ /** Dev-only: build the stack from the local checkout from the next start on.
+ * The main process pushes the new status, so nothing is mirrored here. */
+ async setCheckoutBuild(enabled: boolean): Promise<void> {
+ try {
+ await rpc.localSwitchServer.setCheckoutBuild(enabled);
+ } catch (cause) {
+ this.setError(cause, 'Could not change where switch-core is built from.');
+ }
+ }
+
async reset(): Promise<void> {
runInAction(() => {
this.busy = true;
diff --git a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/remote-server-store.ts b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/remote-server-store.ts
index d066f7adc..db0c4608a 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/switch-servers/remote-server-store.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/switch-servers/remote-server-store.ts
@@ -28,6 +28,9 @@ function defaultStatus(sshHost: string): RemoteServerStatus {
version: '',
deployedVersion: null,
drift: null,
+ // A remote stack always runs the pinned released images — the dev checkout
+ // build is a local-only option.
+ checkoutBuild: null,
message: null,
error: null,
};
diff --git a/console/apps/switch-console-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts b/console/apps/switch-console-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
index ab9eb7b6e..22f9ee9cb 100644
--- a/console/apps/switch-console-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
@@ -72,6 +72,28 @@ export function switchVersionDowngradeMessage(deployed: string, expected: string
);
}
+/**
+ * Image tag a checkout build is tagged with. Deliberately not a semver and
+ * deliberately not the pin: it must never be mistaken for a released version,
+ * and it must not overwrite the pinned image in the local image store. Shared
+ * because the renderer recognises it too — a stack on this tag is a checkout
+ * build rather than a stack that has drifted.
+ */
+export const CHECKOUT_IMAGE_TAG = 'dev-checkout';
+
+/**
+ * The dev-only "build switch-core from this checkout" option: where the
+ * checkout is, and whether the next start will build from it instead of pulling
+ * the pinned released images. Only ever offered to a dev build running out of a
+ * Switch source tree.
+ */
+export type CheckoutBuild = {
+ /** Absolute path of the checkout the images would be built from. */
+ root: string;
+ /** Whether the option is on. Applies from the next start onwards. */
+ enabled: boolean;
+};
+
/** Snapshot of the managed local server, emitted on every transition. */
export type LocalServerStatus = {
phase: LocalServerPhase;
@@ -84,6 +106,11 @@ export type LocalServerStatus = {
deployedVersion: string | null;
/** Set when {@link deployedVersion} differs from {@link version}, else null. */
drift: SwitchVersionDrift | null;
+ /** Dev builds launched from a Switch checkout only: the checkout the stack's
+ * images can be (or are being) built from, and whether that is turned on.
+ * Null in a released build, and in a dev build that is not running from a
+ * checkout — there is nothing to offer then. */
+ checkoutBuild: CheckoutBuild | null;
/** Human-readable current step (e.g. "Pulling images…"), or null. */
message: string | null;
/** Populated only when `phase === 'error'`. */