Projects

From a new project to daily starts and stops: follow the normal lifecycle of a Roof development environment.

Create a new project

Roof must be installed and Docker running. Open a terminal in the directory where you want your new project folder. In interactive init, choose a managed backend stack, a managed frontend or both, and compatible versions.

Create and start a projectbash

roof init my-project
cd my-project
roof build
roof up

init creates my-project, writes the project configuration to .roof/roof.json, creates role directories and registers the project locally. You do not need init again for a normal restart.
cd my-project changes into the new project directory. Run the following project commands there.
build prepares the local development environment: managed applications are scaffolded when needed, their dependencies installed and required backend images built or pulled.
up starts the selected roles and registers local routes. Open the printed URL; depending on the stack, application steps such as an installer may still be needed.

build is a useful explicit preparation step. up also performs missing scaffold and installation steps. This applies to managed roles; with Custom, you add the application and its dependencies yourself.

Everyday development

Work in the project directory. When returning the next day, roof up is normally enough; then open the project with roof open.

Start the projectbash

roof up

Starts the development environment and prints its URLs.

Open the project in a browserbash

roof open

Opens the configured primary project address. Run roof up first; open does not check whether the application is reachable.

Inspect statusbash

roof ps

Shows role status, project URLs and further runtime information.

Find logsbash

roof logs

Normally lists available Roof logs. If no Roof logs exist yet, a backend project shows Compose output instead.

Stop the projectbash

roof down

Stops the current project, including its frontend process and backend stack, and removes its active gateway route.

Follow a specific logbash

roof logs build

After a build, you can follow its log. Exit the running log view with Ctrl+C. For an existing frontend log, use roof logs frontend instead; following logs requires the tail program on your machine.

Your data is retained

down deletes neither the project directory nor persistent Docker volumes. Your project files and, for example, database data in those volumes remain available on the next start.

Persistence is not a backup. Back up important data separately; data stored only in a container without persistent storage is not protected by this. Use down for normal shutdown, rather than remove in everyday development.

Manage projects

When working with several projects, roof projects shows the projects known to the global Roof registry, including paths, status and URLs. The list does not replace a full application availability check.

List known projectsbash

roof projects

Notes & limits

Use init for new projects in a new or empty target directory. Adopt existing application code through the import workflow. Prepare Custom roles yourself. All flags and exact failure cases stay in the complete command reference.

Next steps

Still need to install Roof? Return to the installation guide. Find further topics for stack selection, configuration and other workflows in the overview.

Check installation →More documentation topics →

Technical reference

Project workflows in the repository ↗Complete command reference ↗