Skip to main content

Setup guide

The setup guide helps Server Admins prepare a CoderFlow Full server for its first task. For installation first, follow the Quickstart.

The guide opens on the dashboard when the server is not yet in use. On its first check, that means no environment has a repository and no task history exists. If CoderFlow cannot check those facts, it leaves the guide closed. Existing servers can open it manually.

Choose Finish later to close it and stop automatic opening. To return, open Server Administration → Setup → Open setup guide. The Admin menu's Setup entry reaches the same page. Progress and choices are saved on the server and shared by all Server Admins. They survive a browser change or server restart. A save failure is shown; closing without a saved dismissal can let the guide open again.

Use Back, Next, or the step list to move around. Skip this step lets you continue without claiming the step is done. Every step works without Ask CoderFlow. Links to other pages show a Back to setup guide bar so you can return to the step you left.

1. AI provider​

Choose Add Account for an AI provider. Sign in with a supported subscription or enter an API key, then choose the account under Tasks use. API keys are checked when saved. If a key is saved but unconfirmed, choose Test on the account and resolve the result. This step is done when the server reports an account ready for tasks. Existing accounts appear here too.

The optional section explains a server Claude API key and Allow Actions for Ask CoderFlow. A Claude subscription can run tasks but does not enable Ask or the helper features. Add a server Claude API-key account if you want those features. Change Allow Actions through the link to Server Settings. See AI provider authentication.

2. Code​

Choose where your code lives:

  • GitHub — Choose Connect GitHub to create and install a GitHub App through Server Settings. You need permission to create the app in your account or organization. Agents can clone, push and open pull requests.
  • Azure DevOps — Choose Connect Azure DevOps to add an organization and its service principal. Test the connection before saving. Agents can clone, push and open pull requests.
  • Other Git host (access token) — Use an HTTPS repository on GitLab, Bitbucket, Gitea or another host. In step 4, create a Draft, then save the token on its Secrets tab with Use as Git PAT (Personal Access Token) enabled. Agents can clone and push. Approving changes commits and pushes to your chosen branch or a new branch. CoderFlow cannot open a pull request for these repositories; create it on your Git host after pushing.
  • Host in CoderFlow — CoderFlow keeps the repository on this server. You need no external Git account. Step 4 creates the repository with the environment, and Upload files adds your source. Approving a task commits to the hosted repository. There are no pull requests.
  • Try a reference app — Choose a ready-made sample in step 4. Later, add another environment for your own code.

If Git access is already configured, Use what's connected keeps it. Nothing is replaced. For GitHub or Azure DevOps, the step is done when the choice is saved and the server reports a connected Git provider. The other three choices are done once saved; they do not claim the code is already imported. Use what's connected stays done while the server reports an existing provider, access-token secret or hosted repository.

See Git Providers and Git access-token secrets.

3. What agents work on​

Choose everything that applies. Saving at least one answer completes this step:

  • Web app or API — Adds application settings, image and test checks to step 5.
  • Database — Adds a development database connection and its test.
  • IBM i — Adds an IBM i connection, its test and source import. IBM i is IBM's business computing operating system; choose this only if your code uses it.
  • Other — Fits scripts, libraries, command-line tools or documentation. It adds no system requirements and is a complete answer on its own.

You can change these answers later.

4. Environment​

An environment defines the repositories, Docker image, start command, ports and tests used by tasks. A fresh installation has no environments.

  1. Choose Open New Environment or Import a reference app. Your Code answer selects the initial repository option:

    • For a provider, pick the repository.
    • For another Git host with an access token, enter its HTTPS URL. If CoderFlow does not have the token yet, choose Create Draft and detect later, add the PAT secret, then choose Generate configuration.
    • For Host in CoderFlow, create the Draft, choose Upload files, then Generate configuration.
    • For a reference app, choose Load environments, select a sample, then Import.

  2. Review the proposed configuration. Generate from repository creates a Draft. If generation cannot settle the configuration, you can use Create without generating or import a reference app instead.

  3. Follow Finish setup for the environment's missing settings, credentials, build and tests. The last Run a first task step can wait until you reach step 6 of this guide. Step 5 supplies links for systems the environment needs. Build the environment image after the base image is ready. Set Status to Active on Overview when it is ready, then Save.

  4. Use Back to setup guide. If there is one environment, the guide selects it. If there are several, choose which one the remaining steps use.

This step is done when Setup reports an Active environment that has been built. It shows Can't tell when it cannot check, rather than claiming an image is missing. Creating a Draft alone does not complete it. The guide does not build or activate an environment for you.

5. System setup​

This step shows sections for your answers in step 3, using the environment chosen in step 4. Follow each link to configure the item on its own page, then use Back to setup guide. Check again refreshes the facts.

Items show Done, To do, or Can't tell when the server can check them. Not checked means there is no recorded check for that item; it is a link to work you must review yourself. Optional identifies something not needed in this configuration. Choose Next when you have what you need. That records your confirmation of the step; it does not turn unchecked items into passed checks.

Web app or API​

  1. Use Open Application Server to review the start command and ports. An app started inside the task must listen on 0.0.0.0 so the task proxy can reach it. A configured proxy to an existing server is also supported.
  2. Use Open the Build tab to build the image and review its result.
  3. Use Open the Tests tab to define and run a named test. The guide reports a passing test when a checked Finish setup step records it.
  4. For a Draft, Configure this environment opens the setup agent's panel. Review its budgets before launching. You still review the result and set the environment Active yourself.
  5. Use Open Connections for Test reachability if the app needs an internal API or package registry. It checks DNS, TCP, TLS and HTTP from a container on the environment's image.

The application itself runs in the task container and needs no external connection record. See Web Application Environments.

Database​

Use Add a Database connection to connect to an existing development or test database. The dialog offers SQL Server, PostgreSQL, or MySQL (also MariaDB). Use a read-only or development-only user, and run Test connection. See Database connections and Least privilege.

If another environment you manage already has the connection, Reuse from another environment copies it on the server and tests it again. A Draft generated with a local development database needs no database connection while tasks use that local database.

IBM i​

Follow the items in their displayed order:

  1. Choose Add an IBM i connection. The guide ticks and marks SQL, Build objects, and Sync changes to source members as recommended. If you also chose Web app or API, it adds Agent interactive sessions and Profound UI htdocs files. You can change every choice. SSH and Agentic Display Files are available in the dialog but are not marked recommended by the guide.
  2. Choose the transport. Direct suits a server that can reach IBM i. CoderFlow Bridge lets IBM i connect out to CoderFlow. See Choosing a transport.
  3. Use How to set up IBM i user profile in the connection dialog for commands to create a dedicated profile. See the user-profile setup helper.
  4. Run Test connection. Review sign-in, authorities, Remote Access Server and Profound UI readiness for the features you selected. See Check setup.
  5. Turn on IBM i Source Import for the repository that will receive the source. Use Import IBM i Sources from the guide when offered, or from the dashboard's Quick Actions menu with that environment selected. See Import Sources.

Import a reference app is also available if you want sample source before importing your own. The IBM i reference app includes its own Finish setup steps.

Other​

There is nothing additional to configure here. Agents work with what the repository holds.

6. First task​

The guide checks the selected environment and AI account before offering Start the first task. A Draft must be made Active, and an environment without an image must be built. If CoderFlow cannot inspect a prerequisite, it says Can't tell; a task launch still has to pass the server's checks.

  1. Choose Start the first task. It opens New Task with the shipped Get to know this repository template and a suggested task name. Review the environment and agent, then choose Launch task.
  2. Return to the guide and choose Check again to see its progress: Not started, Running, Didn't finish, Finished, or Can't tell. Use Open the task to inspect the result.
  3. Compare the evidence with the four success criteria: the task finishes, the build and tests pass, the app starts, and a screenshot shows it running. The template asks for the commands, results and anything that prevented a check. It changes no files. Missing tests or an application that cannot start are still unverified.
  4. When the task has finished and you have reviewed its result, choose I've checked the result. This completes the guide step. Choosing another environment in the guide withdraws that confirmation.

The step also completes when Setup's First verified task row is Ready. That row has a separate rule: a finished task must have a person's approval of its changes or a passing named test run from Testing → Run Test Commands. It stays Ready once recorded. Since this template changes no files, run a named test on its finished task to reach that status. If necessary, define one on the environment's Tests tab first. See Running tests.

A manual I've checked the result confirmation does not make the Setup row Ready. A task merely finishing does not prove all four success criteria passed.

7. Team​

All items are optional:

  • Open Users — Use Create User to add people. Skip password (send setup link to user) opens Password Setup Link, where you can choose Copy Link. With email configured, Email Link sends it. Use Open Email settings to set up delivery when needed. See People & Access.
  • Open Roles — Review the predefined roles or create a custom role.
  • Open Teams and Open Access — Group people and grant them roles on the environments they need.
  • Open SSO settings — Configure single sign-on through your identity provider.

Choose Done to complete the guide. The Setup guide finished screen confirms completion. You can reopen it from Setup later.

The Setup page​

Open Server Administration → Setup, or Setup in the Admin menu. This Server Admin page reads the current installation and explains what to fix. Open setup guide opens the seven-step guide on the dashboard.

RowWhat it checks
LicenseWhether a usable license is installed and a restart is needed
DockerWhether Docker can be reached
Base imageWhether the shared image exists, its build state and freshness
AI provider for tasksWhether a server account is ready to run tasks
Server Claude API keyThe key needed by Ask CoderFlow and helper features
Git provider or access tokenGit providers, PAT secrets or hosted repositories
Setup repository remoteHosted, external, or no remote
Active environment, builtWhether an Active environment has been built
First verified taskThe recorded task approval or passing named test described above
Site URL and TLSThe server's public URL and TLS configuration
Email (SMTP)Optional email delivery configuration
Single sign-on (SSO)Optional identity-provider configuration

Statuses are Ready, Action needed, Check, Unknown, and Not set up. Read each row's explanation and follow its link. Unknown means the check could not determine the answer. It is not a failed check or proof that something is absent. Not set up is used for optional features. The guide calls an unknown result Can't tell.

The doctor command reads the same Setup checks plus host checks from a terminal. Finishing or dismissing the guide does not change these readiness checks.