You need Git, Docker, and Docker Compose. Docker must be running. This starts the default stack on your machine, including PostgreSQL and Redis.
TERMINAL · LOCAL EXPLORATION
git clone --branch develop https://github.com/santapong/Cooker.git
cd Cooker
docker compose up --build
When the services are ready, open localhost:8080. If ports 8080, 5432, or 6379 are occupied, adjust your Compose override; leave unrelated services running.
Ready to test real execution?
Follow the repository’s UAT guide to configure a Docker host, registry, and the target you want to test. The real-execution path has prerequisites beyond the command above.
Use docker compose down from this checkout to stop its stack. Omitting -v preserves its named volumes. UAT teardown is a separate workflow and can delete its data; read that guide before using it.
A reviewed App connects a GitHub repository to a deployment plan you can inspect before you run it.
From repository to reviewed App
Choose the repository
Open Apps → New app. Pick your GitHub repository and the branch, tag, or commit you want to inspect.
Choose the Compose files
A Compose file describes the services in your application. Add the base file first, then overrides in the order you want them applied.
Inspect the plan
Read the services, build inputs, and diagnostics. A diagnostic tells you what needs attention; resolve blocking items before moving on.
Set the destination and settings
Choose the configured compute target, registry where needed, deployment prefix, and Environment bindings. The prefix helps distinguish your workloads from other deployments.
Save, then choose when to deploy
Saving records the reviewed source. Deployment is a separate, manual action. When you start a deployment, follow the run and open its stage logs.
A review stays tied to the code you saw
Cooker saves the exact Git commit that was reviewed. If someone later changes the branch, that does not silently update or redeploy this App. Reinspect when you are ready to review new code.
Technical detail: commits and environment bindings
The source is pinned to an exact commit SHA. Environment bindings reference keys configured in Cooker, such as DATABASE_URL=CLOUD_DB_URL. The right-hand name refers to the stored Environment key; it is not a literal database password.
Build arguments are not a secret transport. Do not put private values into Docker build arguments or into documentation examples.
Check the result people actually use
A completed run tells you about its execution steps. Also verify that the application starts correctly, serves the intended route, and reaches its database if it uses one. A generated Kubernetes Service does not automatically create a public URL.
A run is one attempt to execute a workflow. Its stages show where work is waiting, happening, or finished.
What each status means
Status
In plain language
Your next step
◷ Pending
Work has not started yet.
Look for a dependency or a waiting step.
↻ Running
Execution is in progress.
Open the current stage’s logs.
✓ Success
The workflow reports completion.
Verify the deployed application too.
× Failed
A step could not complete.
Read the failing stage’s error.
− Cancelled
A cancellation was recorded.
Check what completed before cancellation.
Find the useful part of a log
Open the run
Use its project and timestamp to make sure you are looking at the correct attempt.
Select the stage that needs attention
For a failure, start with the failing stage. Read the first meaningful error and the lines immediately before it.
Share enough context to help
Give your teammate the run ID, stage name, time, and a short description. Remove secrets before sharing logs.
Success has a specific meaning
Successful execution does not prove that every user journey works, a public URL exists, or a database read and write succeeded. Those need their own checks.
Technical detail: cancellation and interrupted runs
Cancellation is cooperative. Completed stages are not rewound. After a restart, the server can mark runs with stale heartbeats as failed; this is not automatic workflow resumption.
Cooker uses infrastructure you configure. It does not create your cloud account, database, network, or virtual machines.
Choose the destination for your stack
Destination
Current reviewed App scope
Docker Compose
Native stacks on the Cooker host, with service DNS and named volumes.
Kubernetes
Deployments and Services on an existing cluster. Public ingress needs separate configuration.
ECS Fargate
Supported services on an existing AWS setup.
Cloud Run
A supported single-container path on an existing GCP project.
Connect an existing database
Keep the database where it already lives. Configure its connection value in a Cooker Environment, then bind the application’s expected variable to that key. Verify connectivity from the deployed workload.
Technical detail: binding a variable
For example, DATABASE_URL=CLOUD_DB_URL maps the application’s DATABASE_URL to a stored Cooker key named CLOUD_DB_URL. This is a reference, not a credential value. Database provisioning and migration planning remain your responsibility.
Current scope to plan around
One compute target per stack and one replica per service.
Target compatibility depends on the Compose features your application uses. Resolve the inspection diagnostics.
Host mounts, privileged settings, and other unsupported features can block deployment.
Source builds currently require the Docker builder and pusher in dev/UAT. Production validation rejects that pair; a compatible production source-build path remains pending.
Live cloud acceptance is pending. Check the UAT plan before relying on a target for a production rollout.
Selected projects appear in Cooker's real Pipelines view after successful synchronization. This developer reference explains the catalog contract, deployment identity and read-only ownership.
Open the actual workspace
Sign in to your Cooker instance, open Pipelines, and find the project under Vercel provider flows. Select Inspect provider flow →. The Managed by filter offers Vercel · read-only. Apps and Services expose the same selected project and deployment context.
Real provider records and authored DAGs have different owners.
The Vercel section reflects synchronized projects. Cooker's native section contains executable DAGs. Opening a provider flow does not create a native pipeline or start a deployment.
Read the catalog API
Use the existing authenticated API session. These request examples are read-only and contain no credentials. Replace :id with the identity returned by the corresponding catalog list.
HTTP · AUTHENTICATED READS
GET /api/v1/catalog/pipelines?provider=vercel&management=vercel&limit=50&offset=0
GET /api/v1/catalog/pipelines/:id
GET /api/v1/catalog/apps?provider=vercel
GET /api/v1/catalog/apps/:id
GET /api/v1/catalog/services?provider=vercel&environment=production_first
Lists return items, total, limit, offset and sources. Filtering precedes pagination; the default limit is 50 and the maximum is 100. Search uses q. Common filters are provider and management; services also support appId, environment and status.
Follow a flow's returned href to its workspace page. Use its appId to find services. Catalog identities derive from provider account/team scope and project ID, so a project rename preserves identity. Imported IDs do not identify executable native pipeline records; their capabilities allow inspection and expose no edit or deploy action.
Understand the release model
The graph and text step list describe source used by deployment → deployment sent to destination. Reported components share that deployment. These arrows do not describe startup dependencies, runtime traffic or an executable DAG recovered from Vercel.
Current production is separate from the latest preview and recent activity. A newer failed release does not replace the reported production destination. Choose a release in the deployment selector or follow its link with ?deployment= to inspect that exact release. Confirmed production aliases and unique deployment URLs remain separate; either may require access permission.
Vercel READY means provider deployment readiness, rather than a successful application health probe. Missing service metadata remains unavailable. Framework names do not imply a database, queue or independently deployed worker. The Uploaded Cooker landing bundle source is attributed only when its deployment matches the saved publication receipt.
Check freshness and missing projects
Check selected projects in Settings and connection status in Cloud. Sync polls every two minutes. Paused or failed sync retains labelled last-known data; deselection or disconnect removes visibility without deleting a Vercel project. Inspect list sources and per-record freshness warnings before treating results as complete.
Response
Interpretation
401
Sign in with your existing Cooker account.
404
The identity is missing from an available matching source. Check selection and the returned catalog ID.
503
The matching source is unavailable. Check connection and freshness warnings before retrying.
Direct Vercel log ingestion and provider deployment controls are outside this catalog. Use the flow's verified Vercel dashboard links for provider inspection.
Scope: the local Cooker candidate's catalog handlers, model and unified catalog reference, checked 2 October 2026. These features may differ from the published develop branch.
Build & operate / API & command line
Go a level deeper.
Use the interface for the visual workflow. Use the API and command-line client when your tools need to work with Cooker.
Start with read-only checks
These examples query a Cooker server running locally on port 8080. They do not start a run or modify a project.
Application API routes use the /api/v1 prefix. Authentication and permissions depend on the server configuration. Keep tokens out of URLs, shared screenshots, and shell history.
Consult the route implementation alongside the reference when integrating. Some management endpoints remain placeholders; a listed route is not proof that every operation is implemented.
The cookerctl client
The repository includes a command-line client for listing pipelines, importing and exporting YAML, triggering runs, and reading logs. After building the client from backend/cmd/cookerctl, use its help to inspect the available flags.
TERMINAL · INSTALLED CLIENT
cookerctl --help
cookerctl --server http://localhost:8080 pipelines list
Technical detail: command-line authentication
The client supports COOKER_URL for the server address and COOKER_TOKEN for a token. Prefer the token environment variable over a literal --token argument. Create and manage tokens through your instance’s supported settings and access policy.
Find your symptom, try the smallest useful check, and bring the right context to the person who can help.
I can’t sign in
Confirm the workspace address and ask your administrator which sign-in method is enabled. Local account access and organization single sign-on have different recovery paths.
For operators: a redirect keeps looping
Compare the configured public URL, identity-provider redirect URI, and frontend/backend authentication settings. Consult the login troubleshooting source. Do not use disabled authentication as a production recovery shortcut.
My run looks stuck
Open the current stage and read the latest log lines. If the log view stopped updating, refresh the view and check the run again before starting another attempt.
For developers: things to inspect
A build command may be running a foreground server instead of a command that exits. A deployment may be waiting for resources, failing to pull an image, or restarting. Check the target’s workload events and logs to distinguish these cases.
I can’t finish the App review
Read each blocking diagnostic. Confirm the selected Compose file order and the target’s supported features. Ask the operator about missing registry or Environment configuration.
The run succeeded, but the app does not work
Check that the workload is healthy, its route is configured, and the app can reach its dependencies. For external databases, verify a real read and write from the application. Run success alone does not establish these outcomes.
Make the next conversation easier
Include the project, run ID, stage, approximate time, what you expected, and the error you saw.
Share only the log lines needed to explain the issue. Remove tokens, passwords, and private connection values.
Cooker