# Lab 8: Publish your app to Render, then extend it

Your Library web app published from the editor to a new GitHub repository, deployed on Render's free tier, then extended with a Publisher concept and redeployed.

| Time | Level | Runs with | Do first | Track |
| --- | --- | --- | --- | --- |
| 45 min | Intermediate | Browser, GitHub | [Lab 7](https://labs.besser-pearl.org/labs/web-app/) | Full applications |

**You'll learn to**

- Connect the editor to GitHub and publish a project as a new repository
- Explain what the generated repository and its Render Blueprint contain
- Deploy the backend, frontend and agent services on Render's free tier
- Change the models, update the same repository and redeploy

**You'll need**

- The Library App project from the web-app lab (or its JSON export)
- A GitHub account
- A free Render account (you can sign up with GitHub)

**Files for this lab**

- [Starting project: Library App (JSON)](https://labs.besser-pearl.org/files/deploy-render/library-app.json)

Online version: https://labs.besser-pearl.org/labs/deploy-render/

---

In the [web-app lab](https://labs.besser-pearl.org/labs/web-app/) you ran the generated application on your own machine. Here you put
the same application on the internet. The editor generates the code, pushes it to a new repository in your
GitHub account together with a `render.yaml` Blueprint, and Render builds and hosts the three services that
Blueprint describes.

Then you do what real projects do next: change the requirements. You add publishers to the domain model,
teach the agent a new question, update the GUI and publish again to the same repository.

> **Before you continue**
>
> This lab creates a repository in your GitHub account (public by default) and three services in your Render
> account. The services use Render's free plan, which costs nothing but sleeps after 15 minutes without
> traffic. Delete the Blueprint on Render and the repository on GitHub when you no longer need them.

## 1. Open the project and check the models

1. Open [editor.besser-pearl.org](https://editor.besser-pearl.org/) in the same browser you used for the
   web-app lab. Projects live in the browser's storage, so `Library App` is still there: open it with
   **File > Open Project**.
   If you use a different browser, download the [starting project](https://labs.besser-pearl.org/files/deploy-render/library-app.json) and open it
   with **File > Import > Project file (.json / .py)**.
2. Run **Quality Check** on the **Class** and on the **Agent** diagram. Both report "Diagram is valid".
3. Open the **GUI** editor and check that the Book page still has the Library assistant widget with
   `Greeting Agent` selected in its **Agent** field.

> **Note**
>
> Publishing needs a class diagram and a GUI model (for a web app) or an agent diagram (for a standalone
> agent). **Deploy > Publish to Render** is only enabled while a Class, GUI or Agent diagram is open.

> **Check your work**
>
> The project has a valid Library class diagram, a valid Greeting Agent, and a GUI whose Book page contains the
> table, the chart and the chat widget.

## 2. Connect GitHub

1. Open the **Deploy** menu. While you are not signed in, it shows two items.

![Deploy menu with the Deployment header, Connect GitHub to Deploy and Publish to Render](https://labs.besser-pearl.org/labs/deploy-render/deploy-menu-signed-out.png "Connect GitHub to Deploy disappears once you are signed in")

If you click **Publish to Render** now, the editor only shows a reminder:

![Information toast: Connect to GitHub first.](https://labs.besser-pearl.org/labs/deploy-render/toast-connect-github-first.png "Publishing always starts with a GitHub sign-in")

2. Click **Deploy > Connect GitHub to Deploy** (or the GitHub icon in the top bar). The editor redirects you
   to GitHub.

![GitHub sign-in page asking you to continue to BESSER Web Modeling Editor](https://labs.besser-pearl.org/labs/deploy-render/github-sign-in.png "Check that the page names BESSER Web Modeling Editor before you sign in")

3. Sign in and authorize the application. It asks for the `repo`, `gist` and `user` scopes, because it creates
   repositories and pushes code on your behalf.
4. Back in the editor, a toast says "Signed in as" followed by your GitHub user name.

> **If something goes wrong**
>
> If you return to the editor and still see **Connect GitHub to Deploy**, the sign-in did not complete. Try
> again in a normal (not private) window and allow pop-ups and redirects for editor.besser-pearl.org. The
> session lasts 24 hours; after that, sign in again.

> **Check your work**
>
> The **Deploy** menu now shows only **Publish to Render**, and the top bar shows your GitHub account.

## 3. Publish the project to a new repository

1. With the **Class** or **GUI** diagram open, choose **Deploy > Publish to Render**. The
   **Publish to Render** dialog opens with the text "Create a GitHub repository from the current project and
   deploy it on Render."
2. Fill in the fields:
   - **Deployment Target**: **Web App (Class + GUI)**. This field only appears when the project could
     also be published as a **Standalone Agent**.
   - **Repository Name**: proposed from the project name in lower case, here `library_app`. Use something unique
     in your account, such as `library-app-lab`.
   - **Description**: defaults to "Web application generated by BESSER".
   - **Make repository private**: leave it off. The dialog warns that private repositories may require
     manual Render permission setup.
3. Click **Publish to Render**. The button reads "Publishing..." while the editor generates the code and
   pushes it.
4. The result dialog is titled **Repository Created Successfully**. It shows `<your-user>/<repository>`, the
   number of files uploaded, and two buttons: **Open Render Deployment** and **View GitHub Repository**.

> **Note**
>
> No screenshots of these two dialogs are included because they only appear after a GitHub sign-in. The
> labels above are taken from the editor's source code (BESSER 8.0).

> **Check your work**
>
> The result dialog says **Repository Created Successfully**, and the repository exists on github.com under
> your account.

## 4. Inspect the generated repository

Click **View GitHub Repository**. The commit pushed by BESSER is called "Initial commit - Generated by
BESSER Web Editor", and the repository contains:

```text
library-app-lab/
├── README.md              overview, project structure and a Deploy to Render button
├── render.yaml            the Render Blueprint
├── docker-compose.yml     the local setup you used in the web-app lab
├── BESSER_GENERATION.md   BESSER version and generator used
├── backend/               FastAPI + SQLAlchemy
├── frontend/              React + TypeScript (Vite)
├── agents/
│   └── greeting_agent/    the BESSER Agentic Framework agent
└── buml/
    ├── domain_model.py    the class diagram as B-UML Python code
    ├── gui_model.py       the GUI model as B-UML Python code
    ├── agent_model_greeting_agent.py
    └── diagrams.json      the project, re-importable in the editor
```

Open `render.yaml`. It declares one service per part of the application. This is its shape (names are
shortened; yours contain the repository name and a six-character suffix):

```text
services:
  # Backend API (Free tier - 750 hours/month, spins down after 15 min idle)
  - type: web
    name: library-app-lab-backend-<suffix>
    runtime: python
    plan: free
    buildCommand: pip install -r backend/requirements.txt
    startCommand: cd backend && uvicorn main_api:app --host 0.0.0.0 --port $PORT

  # Frontend (Free static site)
  - type: web
    name: library-app-lab-frontend-<suffix>
    runtime: static
    buildCommand: cd frontend && npm install && npm run build

  # Agent Service: Greeting_Agent (Free tier - WebSocket-based AI agent)
  - type: web
    name: library-app-lab-greeting-agent-agent-<suffix>
    runtime: python
    plan: free
```

The frontend is built with the backend's and the agent's public `onrender.com` addresses, and the agent's
start command rewrites its `config.yaml` to listen on `0.0.0.0` and Render's port. That is why the
`host: 0.0.0.0` edit from the web-app lab is not needed on Render.

> **Check your work**
>
> You can name the three services the Blueprint will create and find the folders that each one builds from.

## 5. Deploy the Blueprint on Render

1. Back in the editor, click **Open Render Deployment**. It opens Render's deploy page for your repository
   (`https://render.com/deploy?repo=https://github.com/<your-user>/<repository>`). The
   **Deploy to Render** button in the repository's README opens the same page.
2. Sign in to Render (signing in with GitHub is the simplest) and, if Render asks, give it access to the new
   repository.
3. Enter a **Blueprint Name**, keep the **Branch** `main` and the default **Blueprint Path**
   `render.yaml`, review the three services, and click **Deploy Blueprint**.

![Render Blueprint form with Blueprint Name, Branch main, Blueprint Path and three services to create](https://labs.besser-pearl.org/labs/deploy-render/render-blueprint-review.png "Render's own page. Captured from an earlier deployment, so the service names differ from yours")

> **Before you continue**
>
> If Render asks for a value for `OPENAI_API_KEY`, it belongs to the agent service. It is only needed for
> agents that call a language model (LLM-based intent recognition or LLM replies). The Greeting Agent uses
> fixed replies; enter a key only if your own agent needs one, and never commit it to the repository.

4. Wait. On the free plan the three services take between 4 and 12 minutes to build and start. Render shows
   the progress of each service.
5. When all three are live, open the frontend service (its name contains `-frontend-`) and click its
   `onrender.com` address.

The app is the one you ran locally, but empty: the Render backend has its own SQLite database. Add a
library, an author and a book through `https://<backend-service>.onrender.com/docs`, exactly as in the
web-app lab, and reload the frontend.

> **If something goes wrong**
>
> A service that has not been used for 15 minutes sleeps, so the first page load or chat message after a pause
> can take a minute. If the chat widget stays on "Connecting to agent...", open the agent service on Render
> and check that it is live and that its log shows the WebSocket platform starting.

> **Check your work**
>
> The Blueprint shows three services as deployed, the public frontend URL shows the Book page, and the chat
> widget answers "Hello" with "Hi" and "How are you?".

## 6. Extend the domain, the agent and the GUI

The library now needs to track publishers. A publisher has a name, a country and a founding year; it
publishes many books, and each book has one publisher. The application must also compute the average price
of a publisher's books.

1. **Class diagram.** Add a `Publisher` class with `name: str`, `country: str` and `founded: int`. Connect it
   to Book with an association: multiplicity `1` on the Publisher end and `*` on the Book end.
2. Add the method. In the Publisher properties panel, click **Code** under **METHODS**, rename the new method
   to `average_book_price(): float`, set **TYPE** to **Python Code**, and write the body in the
   **Python Implementation** editor:

![Publisher class with name, country and founded, and average_book_price implemented as Python code](https://labs.besser-pearl.org/labs/deploy-render/publisher-method-python.png "A method body can be Python Code or BESSER Action Language; self.books is the association end you just drew")

The code in the screenshot:

```python
def average_book_price(self) -> float:
    if not self.books:
        return 0.0
    return sum(book.price for book in self.books) / len(self.books)
```

Run **Quality Check**. If you prefer the BESSER Action Language, the Library class's `cheapest_book_by`
method is an example of its syntax.

3. **Agent.** Open **Agent** > **Components** and, in the **Intents** section, click **Add Intent**.
   Name it `publisher_price_intent` and use **Add sentence** to add, for example:
   - `how can I get the average price of books from a publisher?`
   - `average book price for a publisher`
   - `how do I compute the publisher average price?`
4. In the Agent diagram, add a state `publisher_help` whose body is a **Text** reply such as "Open the
   Publisher page, select a publisher in the table and click average_book_price." Draw a transition from
   `initial` to `publisher_help`, open it, choose **Intent Matched** and the new intent. Draw a second
   transition from `publisher_help` back to `initial` of type **Auto**.
5. **GUI.** Run **Auto-Generate GUI from Class Diagram** again. It creates the new Publisher page with its
   table and an **average_book_price** button.

> **Before you continue**
>
> Auto-generation rebuilds the whole GUI and removes the BESSER Agent widget and the bar chart you added in the
> web-app lab. Add them again afterwards, and choose `Greeting Agent` in the widget's **Agent** field.

> **Check your work**
>
> Quality Check passes on the Class and Agent diagrams, the **Pages** panel lists Book, Library, Author and
> Publisher, and the Book page has the chat widget again.

## 7. Redeploy and test the changes

1. Choose **Deploy > Publish to Render** again. Because the project is linked to the repository, the dialog
   now says "Update the existing repository with your latest changes.", shows "Previously deployed to:" with
   your repository, and offers a **Commit Message** field (leave it empty for the default
   "Update app - Generated by BESSER Web Editor"). Files you added to the repository by hand are kept.
2. Click **Update & Publish**. The result dialog is titled **Repository Updated Successfully** and offers
   **Open Live App**, **Open Render Blueprint** and **View GitHub Repository**.
3. Render normally redeploys after a push. If your changes do not appear after a few minutes, open the
   Blueprint on Render and click **Manual Sync**: it redeploys every service from the latest commit.
4. Open the live app and check that:
   - the Publisher page exists and you can create a publisher;
   - after you create books for that publisher through the API (the book body now also needs the publisher's
     id; the `BookCreate` schema in Swagger shows the field name), **average_book_price** returns their
     average price;
   - the agent answers "average book price for a publisher" with your instructions.

> **Note**
>
> Choosing "Create new repo instead" in the dialog publishes to a fresh repository and needs a new Blueprint,
> which means three more services in your Render account.

> **Check your work**
>
> The repository has a second commit, the live app shows the Publisher page, and the agent answers the new
> question.

## 8. Exercise: keep evolving the application

> **Exercise: Add a statistics question to the agent**
>
> Add a method `book_count(): int` to Publisher, a matching intent and agent state, and a **Metric Card / KPI**
> or chart on the Publisher page. Publish the update and verify each part in the live app.

<details>
<summary>Show a solution</summary>

`book_count` can reuse the same association end as `average_book_price` (`len(self.books)`). Remember the
order of the GUI work: auto-generate first, then re-add the widgets that auto-generation removes.

</details>

> **Exercise: Publish only the agent**
>
> Open the Agent diagram and choose **Deploy > Publish to Render**. Switch the **Deployment Target** to
> **Standalone Agent** and compare the generated repository and `render.yaml` with the web app's.

<details>
<summary>Show a solution</summary>

The dialog proposes a repository name ending in `-agent`, and the button reads **Publish Agent to Render**.
Look at how many services the agent Blueprint declares and which user interface it starts.

</details>

---

Checked against BESSER 8.0 on 2026-10-02.
