Your first project: from model to first record

This guide creates an application for articles: define fields in Generator UI, generate a Go backend and React admin, then save your first record. The project model is stored in .admingen/project.yaml, but you do not need to edit that file manually.

First prepare the tools: admingen (UI) and admingen-cli (CLI) must be available in PATH. The application requires Go, Node.js/npm, Make and Docker with Compose v2. Required versions are listed in the generated project files. Creating the directory and starting processes currently requires a terminal; commands are collected in the preparation section below.

1. Open the project in Generator UI

Start the local editor and open the address printed by admingen. On Dashboard, check that the correct project is selected. In Project settings, set the title displayed in the interface. Here you configure the application; you will add articles later in the generated admin.

2. Define articles in Content

Open Content → New module and create the content module. Then click New entity: create a persistent entity named Article with the articles table. Persistent means its records are stored in the database. Use Add field to add:

• id with the Identifier int64 preset: a primary key with generated values;
• title with type String and Required enabled;
• body with type Text and Markdown presentation.

Click Finish after configuring each field. Check the saved fields' types and properties in the table. To add sections and relationships immediately, continue with the CMS guide.

3. Review changes and Generate

Go to Generate and click Preview changes. Review the files that will change and the impact on access and API routes. Inspect the differences, resolve model errors and conflicts, then click Generate. The generator creates the backend, admin, migrations, API and remaining project files.

Distinguish three steps: saving the model, generating files and applying database changes. Generate performs the second step. Afterwards, you still need to start the application and apply migrations.

4. Create your first record in the admin

Run the startup command below. The terminal will offer to create the first superadmin: set a username and password; there is no shared default password. Open the admin address printed in the output, sign in and select Article. Enter a title and body, save the article, then open it again.

You can now edit the article title and body in the admin. They are saved in PostgreSQL; Generate is unnecessary. To add a field, return to Generator UI, change the model, Generate and apply the migration.

Terminal preparation and startup

In a terminal, go to the directory where you want to create the project. These commands create docs-demo once and start its editor:

admingen-cli --path ./docs-demo init \
  --name docs-demo \
  --title "База знаний" \
  --module example.com/docs-demo \
  --generator-version 0.8.1
admingen --path ./docs-demo start --addr 127.0.0.1:8080

Here --path is the project directory, --name its technical name, --title its interface title and --module the Go module path. You do not need to register example.com; it is part of this example. Init creates .admingen/project.yaml. If no Git repository exists, it also attempts to initialize a local repository, without a remote or first commit.

After Generate in the browser, open another terminal and start the application from the project root:

cd docs-demo
make dev

make dev prepares the environment, starts PostgreSQL, applies migrations, offers to create a superadmin, then starts the backend and admin. Open the application address printed in the output: it differs from the Generator UI address.

Optional: the same cycle through CLI

You can also edit the model with CLI commands, for example in a script. View the plan and apply generation with:

admingen-cli --path ./docs-demo plan
admingen-cli --path ./docs-demo generate --dry-run
admingen-cli --path ./docs-demo generate

Dry-run displays proposed changes without writing anything. UI and CLI use the same model; choose whichever suits the task.

Troubleshooting

• Command not found: check PATH or use the binary's absolute path.
• Port occupied: choose another --addr for Generator UI; application ports are configured separately.
• Docker unavailable: start Docker and retry local startup.
• Incompatible version: the current contract is 0.8.1. Editing the version in an old lock does not upgrade the project.
• Generate conflict: inspect the differences and preserve necessary manual changes before allowing overwrite.

Next: create a CMS through the UI, local development, safe model changes.

After your first project

For the remaining screens, open UI interface. Settings are covered separately: Content, field settings, access. For terminal work, use CLI interface.