diff --git a/app/frontend/src/features/secondary/pages.tsx b/app/frontend/src/features/secondary/pages.tsx
index 8a68467..1bbab92 100644
--- a/app/frontend/src/features/secondary/pages.tsx
+++ b/app/frontend/src/features/secondary/pages.tsx
@@ -1253,7 +1253,11 @@ export function GitHubAppCallbackPage() {
mutationFn: (appCode: string) => convertGitHubAppCode(appCode),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['github-app-status'] });
- navigate('/settings', { replace: true });
+ // The setup wizard stashes a return marker before submitting the
+ // manifest form — resume there instead of the settings page.
+ const inSetup = sessionStorage.getItem('containr.setup_return') === '1';
+ sessionStorage.removeItem('containr.setup_return');
+ navigate(inSetup ? '/setup' : '/settings', { replace: true });
},
});
const firedRef = useRef(false);
diff --git a/app/frontend/src/features/setup/SetupWizardPage.test.tsx b/app/frontend/src/features/setup/SetupWizardPage.test.tsx
new file mode 100644
index 0000000..2291e20
--- /dev/null
+++ b/app/frontend/src/features/setup/SetupWizardPage.test.tsx
@@ -0,0 +1,92 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import { SetupWizardPage } from './SetupWizardPage';
+import type { SetupStatus } from '@/lib/api-client';
+
+const mockStatus = vi.fn<() => Promise
>();
+const mockSession = vi.fn();
+
+vi.mock('@/lib/api-client', async (importOriginal) => {
+ const mod = await importOriginal();
+ return {
+ ...mod,
+ getSetupStatus: () => mockStatus(),
+ completeSetup: vi.fn().mockResolvedValue(undefined),
+ };
+});
+
+vi.mock('@/lib/use-auth-session', () => ({
+ useAuthSession: () => mockSession(),
+}));
+
+function renderWizard() {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ return render(
+
+
+
+ ,
+ );
+}
+
+const base: SetupStatus = {
+ has_users: false,
+ setup_completed: false,
+ needs_setup: true,
+ has_github_app: false,
+ has_tunnel: false,
+ signup_enabled: false,
+};
+
+describe('SetupWizardPage', () => {
+ beforeEach(() => {
+ mockSession.mockReturnValue({ data: null });
+ });
+
+ it('prompts for the admin account on a fresh install', async () => {
+ mockStatus.mockResolvedValue({ ...base });
+ renderWizard();
+ expect(await screen.findByText(/welcome to containr/i)).toBeInTheDocument();
+ expect(screen.getByText(/create admin account/i)).toBeInTheDocument();
+ });
+
+ it('offers sign-in when users exist but nobody is signed in', async () => {
+ mockStatus.mockResolvedValue({ ...base, has_users: true });
+ renderWizard();
+ expect(await screen.findByText(/sign in to continue setup/i)).toBeInTheDocument();
+ });
+
+ it('shows the git provider step for a signed-in admin without GitHub App', async () => {
+ mockStatus.mockResolvedValue({ ...base, has_users: true });
+ mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+ renderWizard();
+ expect(await screen.findByText(/connect a git provider/i)).toBeInTheDocument();
+ expect(screen.getByText(/set up github app/i)).toBeInTheDocument();
+ });
+
+ it('shows the tunnel step when git is already wired', async () => {
+ mockStatus.mockResolvedValue({ ...base, has_users: true, has_github_app: true });
+ mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+ renderWizard();
+ expect(
+ await screen.findByRole('heading', { name: /public access/i }),
+ ).toBeInTheDocument();
+ });
+
+ it('lands on the finish step when everything is configured', async () => {
+ mockStatus.mockResolvedValue({
+ ...base,
+ has_users: true,
+ has_github_app: true,
+ has_tunnel: true,
+ });
+ mockSession.mockReturnValue({ data: { user: { id: 'u1' } } });
+ renderWizard();
+ expect(await screen.findByText(/enter containr/i)).toBeInTheDocument();
+ });
+});
diff --git a/app/frontend/src/features/setup/SetupWizardPage.tsx b/app/frontend/src/features/setup/SetupWizardPage.tsx
new file mode 100644
index 0000000..6f506c5
--- /dev/null
+++ b/app/frontend/src/features/setup/SetupWizardPage.tsx
@@ -0,0 +1,279 @@
+import { useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Link, Navigate, useNavigate } from 'react-router-dom';
+import { Check, ChevronRight, Github, Loader2, Rocket, ShieldCheck } from 'lucide-react';
+import { useAuthSession } from '@/lib/use-auth-session';
+import {
+ completeSetup,
+ createGitHubAppManifest,
+ getSetupStatus,
+ updatePlatformSettings,
+} from '@/lib/api-client';
+
+// Marker the GitHub App callback reads so the wizard flow resumes here
+// instead of the settings page.
+const SETUP_RETURN_KEY = 'containr.setup_return';
+
+type Step = 'account' | 'github' | 'tunnel' | 'done';
+
+export function SetupWizardPage() {
+ const navigate = useNavigate();
+ const queryClient = useQueryClient();
+ const sessionQuery = useAuthSession();
+ const statusQuery = useQuery({ queryKey: ['setup-status'], queryFn: getSetupStatus });
+ const [override, setOverride] = useState(null);
+
+ const status = statusQuery.data;
+ const signedIn = Boolean(sessionQuery.data);
+
+ const step: Step = useMemo(() => {
+ if (override) return override;
+ if (!status) return 'account';
+ if (!status.has_users || !signedIn) return 'account';
+ if (!status.has_github_app) return 'github';
+ if (!status.has_tunnel) return 'tunnel';
+ return 'done';
+ }, [override, status, signedIn]);
+
+ const completeMutation = useMutation({
+ mutationFn: completeSetup,
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['setup-status'] });
+ navigate('/projects', { replace: true });
+ },
+ });
+
+ if (statusQuery.isLoading) {
+ return (
+
+
+ );
+ }
+
+ // Wizard is optional once the instance is already configured.
+ if (status && !status.needs_setup && !override) {
+ return
+
+
+ {steps.map((s, i) => (
+
+
+ {i < activeIdx ?
+
+ {s.label}
+
+ {i < steps.length - 1 ?
: null}
+
+ ))}
+
+
+ {step === 'account' ? (
+
+ Welcome to Containr
+
+ First boot detected. Create the admin account — registration closes to the public
+ right after, so this account owns the instance.
+
+ {status?.has_users && !signedIn ? (
+
+
+ An account already exists — sign in to continue setup.
+
+
+ Sign in
+
+
+ ) : null}
+
+ {step === 'github' ?
setOverride('tunnel')} /> : null}
+ {step === 'tunnel' ? setOverride('done')} /> : null}
+
+ {step === 'done' ? (
+
+ All set
+
+ Deploy your first service from a git repo, an image, or a template — the dashboard is
+ ready.
+
+ {completeMutation.isError ? (
+
+ {completeMutation.error instanceof Error
+ ? completeMutation.error.message
+ : 'Failed to save setup state'}
+
+ ) : null}
+ completeMutation.mutate()}
+ disabled={completeMutation.isPending}
+ className="mt-5 inline-flex items-center gap-2 h-10 px-6 rounded-[var(--radius-md)] text-sm font-semibold text-[var(--accent-on)] disabled:opacity-50"
+ style={{ background: 'var(--accent-primary)' }}
+ >
+ {completeMutation.isPending ? (
+
+
+ ) : null}
+
+
+
+
Connect a git provider
+
+
+ Provision the instance GitHub App — repo push events then trigger deployments and preview
+ environments automatically. Self-hosted GitLab/Gitea can be added later in Settings.
+
+ {provisionMutation.isError ? (
+
+ {provisionMutation.error instanceof Error
+ ? provisionMutation.error.message
+ : 'Could not start GitHub App provisioning'}
+
+ ) : null}
+
+ provisionMutation.mutate()}
+ disabled={provisionMutation.isPending}
+ className="inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)] disabled:opacity-50"
+ style={{ background: 'var(--accent-primary)' }}
+ >
+ {provisionMutation.isPending ?
+
+ Skip for now
+
+
+
+ );
+}
+
+function TunnelStep({ onNext }: { onNext: () => void }) {
+ const queryClient = useQueryClient();
+ const [token, setToken] = useState('');
+ const saveMutation = useMutation({
+ mutationFn: () =>
+ updatePlatformSettings({ cloudflareTunnelToken: token.trim() || undefined }),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['setup-status'] });
+ onNext();
+ },
+ });
+
+ return (
+
+ Public access (optional)
+
+ Paste a Cloudflare Tunnel token to expose this instance on the internet. Without one,
+ Containr stays reachable on this network — you can add it later in Settings.
+
+
+ {saveMutation.error instanceof Error ? saveMutation.error.message : 'Failed to save token'}
+
+ ) : null}
+
+ (token.trim() ? saveMutation.mutate() : onNext())}
+ disabled={saveMutation.isPending}
+ className="inline-flex items-center gap-2 h-9 px-4 rounded-[var(--radius-md)] text-sm font-medium text-[var(--accent-on)] disabled:opacity-50"
+ style={{ background: 'var(--accent-primary)' }}
+ >
+ {saveMutation.isPending ?
+
+ Skip
+
+
+
+ );
+}
diff --git a/app/frontend/src/generated/api-types.ts b/app/frontend/src/generated/api-types.ts
index 50e3d0f..4e6d672 100644
--- a/app/frontend/src/generated/api-types.ts
+++ b/app/frontend/src/generated/api-types.ts
@@ -5633,6 +5633,90 @@ export interface paths {
patch?: never;
trace?: never;
};
+ "/setup/status": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ /**
+ * First-run setup status
+ * @description Public. Drives the setup wizard — needs_setup is true until setup_completed is recorded. Instances with users and projects that predate the wizard report completed automatically.
+ */
+ get: {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ requestBody?: never;
+ responses: {
+ /** @description Setup state */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": {
+ has_users?: boolean;
+ setup_completed?: boolean;
+ needs_setup?: boolean;
+ /** @description GitHub App credentials configured (manifest flow or env) */
+ has_github_app?: boolean;
+ /** @description Cloudflare tunnel token configured */
+ has_tunnel?: boolean;
+ signup_enabled?: boolean;
+ };
+ };
+ };
+ };
+ };
+ put?: never;
+ post?: never;
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
+ "/setup/complete": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ /** Mark the setup wizard complete */
+ post: {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ requestBody?: never;
+ responses: {
+ /** @description Setup completed */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["MessageResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
"/settings": {
parameters: {
query?: never;
diff --git a/app/frontend/src/lib/api-client.ts b/app/frontend/src/lib/api-client.ts
index 8cda35b..22d19dd 100644
--- a/app/frontend/src/lib/api-client.ts
+++ b/app/frontend/src/lib/api-client.ts
@@ -499,6 +499,23 @@ export async function pingServer(): Promise {
}
}
+export type SetupStatus = {
+ has_users: boolean;
+ setup_completed: boolean;
+ needs_setup: boolean;
+ has_github_app: boolean;
+ has_tunnel: boolean;
+ signup_enabled: boolean;
+};
+
+export async function getSetupStatus(): Promise {
+ return requestJson('/setup/status');
+}
+
+export async function completeSetup(): Promise {
+ await requestJson('/setup/complete', { method: 'POST', body: JSON.stringify({}) });
+}
+
export function getAgentPublicBaseUrl(): string {
return `${API_ROOT}/api/agents`;
}
diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index af0bdfc..058419e 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -3705,6 +3705,50 @@ paths:
type: boolean
description: True when the owner re-opened public registration in Settings
+ /setup/status:
+ get:
+ tags:
+ - Authentication
+ summary: First-run setup status
+ description: Public. Drives the setup wizard — needs_setup is true until setup_completed is recorded. Instances with users and projects that predate the wizard report completed automatically.
+ responses:
+ '200':
+ description: Setup state
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ has_users:
+ type: boolean
+ setup_completed:
+ type: boolean
+ needs_setup:
+ type: boolean
+ has_github_app:
+ type: boolean
+ description: GitHub App credentials configured (manifest flow or env)
+ has_tunnel:
+ type: boolean
+ description: Cloudflare tunnel token configured
+ signup_enabled:
+ type: boolean
+
+ /setup/complete:
+ post:
+ tags:
+ - Authentication
+ summary: Mark the setup wizard complete
+ security:
+ - bearerAuth: []
+ responses:
+ '200':
+ description: Setup completed
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MessageResponse'
+
/settings:
get:
tags: