Beacon Template UI

Welcome to the new template UI for Beacon v2 instances. Please, follow the official documentation website for detailed aspects on how the Beacon template UI works.

UI Deployment

1. Prerequisites

• Docker

Make sure Docker and Docker Compose are installed on your machine. You can verify this by opening up the terminal on your computer and input the following:

docker --version
docker compose version

You should expect both commands printing a version, for example:

Docker version 27.3.1, build ce12230
Docker Compose version v2.29.7-desktop.1

• Code Editor

You will need a code editor (e.g. Visual Studio Code) to:

• Edit the config.json

2. Clone the repository

Open your terminal and navigate to the folder where you want to store the project (for example, your Desktop):

cd Desktop

Then, clone the Beacon Template UI repository:

git clone https://github.com/EGA-archive/beacon-template-ui.git

Once the cloning process finishes, you can open the app inside your code editor, and then go inside the project directory:

cd beacon-template-ui

This means you’re in the correct directory and ready to start editing the configuration.

3. Edit and Customize the Template UI

Before proceeding, make sure that the following files are configured:

• config.json (location: client/public/config/config.json)
• Use client/config/config.example.json as a reference when creating or updating your configuration.
• Make sure client/public/assets/logos is populated with the correct .svg files. You can also use external URLs if your images are hosted elsewhere.

The UI loads config.json at runtime. After the application is deployed, changes to the runtime configuration can be applied without rebuilding the UI. Refresh or reopen the application to load the updated configuration.

4. Start the application with Docker

In your terminal, run:

docker compose up -d --build

Docker will automatically build the image and start the UI container.

5. Verify the Container

To confirm the container is running:

docker ps

Expected output:

CONTAINER ID IMAGE COMMAND STATUS PORTS 123abc456def beacon-template-ui-client:latest "/docker-entrypoint…" Up 10 seconds 0.0.0.0:3000->80/tcp

If it’s visible, the UI is running locally at: http://localhost:3000

6. Stop or Restart the Application

To stop the container:

docker compose down

If you modify only client/public/config/config.json, you do not need to rebuild the UI.Refresh the browser to load the updated runtime configuration.

If the application source code changes, rebuild and restart the container:

docker compose up -d --build

Updating to a new Beacon Template UI Version

The runtime configuration file (client/public/config/config.json) is designed to be reusable across Beacon Template UI releases. When a new version is published, you do not need to recreate your configuration from scratch. To update to a newer version:

1. Keep your existing configuration files

   • client/public/config/config.json

2. Update the Template UI code

   • Either pull the latest changes from the repository (for example with git fetch / git pull), or clone the new version and copy your existing config.json into it.

3. Rebuild and restart the UI

   • Run:

docker compose down
docker compose up -d --build

This step is required every time the Beacon Template UI code changes, because the Docker image must be rebuilt to include the updated UI. As long as your existing config.json matches the configuration expected by the new release, it can be reused without modification. If new fields are introduced in future versions, compare your configuration with client/config/config.example.json and extend it as needed. For further information on how to configure your UI editing the config.json file, please visit the official documentation UI configuration part