# Your first application

Create a project, add an app and serve its first route. Start here if you are new
to Cicadel.

You need Go 1.26.11 or later and PostgreSQL 18. The standard project includes
accounts, so runtime commands need a database.

> [!NOTE]
> This tutorial uses the current release, v0.2.7. Released APIs follow the
> [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#stability-guarantee). See
> [what is included](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#is-cicadel-ready-to-use).

## Ask your agent

Copy this prompt into your coding agent. Change `myapp` and the module path for your project.

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/llms.txt and its quick-start guide.
Create a Cicadel application in ./myapp with module example.com/myapp.
Use the Cicadel version this documentation describes and record the resolved Go dependency versions.
Add a local notes app, register it in project/apps.go, and serve GET /notes/.
Configure PostgreSQL for the standard account and migration workflow. Do not overwrite an existing project.
Run the application checks and tests, start it locally, and verify /notes/ over HTTP.
Tell me the URL, files changed, and checks that passed.
```

For another version, use the [agent setup page](https://cicadel.fauzaanu.com/en/0.2.7/intro/ai/index.md). Its links and prompts follow
the documentation version selector.

## Create the project

Run these commands from the directory that will contain `myapp`:

```sh
export GOPRIVATE=github.com/fauzaanu/cicadel
go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.2.7 startproject myapp example.com/myapp
cd myapp
go mod tidy
export DATABASE_URL='postgres://USER:PASSWORD@localhost/myapp?sslmode=disable'
export CICADEL_DEBUG=true
export CICADEL_SECURE_COOKIES=false
go run manage.go migrate
go run manage.go check
go run manage.go runserver
```

Open `http://127.0.0.1:8000`. Stop the server with Ctrl-C before you continue.

- **Access.** The repository is private. Configure Git credentials with access, and
  set `GOPRIVATE` as shown.
- **Versions.** The generated `go.mod` pins the framework and core modules at the
  CLI's release. Commit `go.mod` and `go.sum` to keep it.
- **Project CLI.** Inside the project, `go tool cicadel` runs that project's CLI.

> [!TIP]
> To follow the development branch instead, use `@main` in place of `@v0.2.7` and
> read the **dev** documentation. See [install a release](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#install-a-release).

## Add and register an app

From `myapp`, create a notes app:

```sh
go tool cicadel startapp notes
```

Add the app to `project/apps.go`. Keep the core registrations:

<!-- example: quickstart/project/apps.go -->
```go
package project

import (
    "example.com/myapp/apps/notes"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/contrib/formsets"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        formsets.App(),
        notes.New(),
    }, nil
}
```

Change `example.com/myapp` if you chose a different module path.

Unlike Django's `INSTALLED_APPS` strings, this is a Go list of app values. Creating a
folder or importing a package does not register an app. This list does.

## Check the route

The generated `apps/notes/urls.go` connects `/notes/` to `Index`:

```go
func URLs() []urls.Route {
    return urls.Include("/notes", "notes",
        urls.Path("GET", "/", "index", Index),
    )
}
```

List the apps, run the checks and tests, then start the server:

```sh
go run manage.go apps
go run manage.go check
go test -race ./...
go run manage.go runserver
```

Fetch the route from a second terminal:

```sh
curl http://127.0.0.1:8000/notes/
# {"app":"notes"}
```

## Make changes

| File | What to change |
| --- | --- |
| `project/apps.go` | Register local and installed apps |
| `project/settings/settings.go` | Set project defaults |
| `apps/notes/urls.go` | Add routes |
| `apps/notes/views.go` | Handle requests |
| `apps/notes/models.go` | Define database models when needed |
| `project/home.templ` | Edit the homepage |
| `project/errors.templ` | Edit the 404, 500 and other [error pages](https://cicadel.fauzaanu.com/en/0.2.7/howto/error-pages/index.md) |

For UI changes, install the CSS tool once. Then rebuild and check:

```sh
go tool cicadel ui css install
go tool cicadel ui build
go tool cicadel ui check --json
```

Restart the server after you rebuild. For automatic rebuilds and restarts, run
`go tool cicadel dev` instead of `runserver`.

## Choose your next step

- [Render a component](https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md).
- [Add htmx interactions](https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md).
- [Install a reusable app](https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md).
- [Add PostgreSQL migrations](https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md).
- [Start with sign-in screens](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md).

## Deploy

Build the server with `go build -o bin/server .`. Then follow
[deployment configuration](https://cicadel.fauzaanu.com/en/0.2.7/howto/operations/index.md).

> [!WARNING]
> `CICADEL_DEBUG=true` and `CICADEL_SECURE_COOKIES=false` are for local development
> only. Do not use them in production.