Create and deploy a custom Topo Project
Introduction
Learn about Topo Projects
Clone and deploy the Hello World Topo Project
Modify the Hello World Topo Project
Create a new Topo Project from an empty directory
Use Agent Skills to author Topo Projects
Next Steps

  Log an issue

  Fork and edit

  Discuss on Discord

Make the greeting emoji configurable

In the previous section, you cloned and deployed the “Hello World” Topo Project. In this section, you’ll modify the project so the greeting emoji can be configured when someone clones it.

Add a new project parameter

On your host machine, navigate to the “Hello World” Topo Project directory:

    

        
        
cd ~/topo-welcome

Open the compose.yaml file in the text editor of your choice.

Find the parameters section under x-topo. It currently contains the GREETING_NAME parameter:

    

        
        
parameters:
  GREETING_NAME:
    description: The text to use in the greeting message
    required: true
    default: "World"
    example: "Markus"

Add a new GREETING_EMOJI parameter as a second clone-time parameter after GREETING_NAME under parameters:

    

        
        
parameters:
  GREETING_NAME:
    description: The text to use in the greeting message
    required: true
    default: "World"
    example: "Markus"
  GREETING_EMOJI:
    description: The emoji to show next to the greeting
    required: false
    default: "🐳"
    example: "🚀"

The parameter is optional, so users can press Enter to accept the default whale emoji.

Note

Make sure that GREETING_NAME and GREETING_EMOJI are indented under parameters. If they’re aligned with parameters, Topo won’t detect them as clone-time parameters and won’t prompt for values.

Pass the emoji to the build

In the same compose.yaml file, find the service build arguments:

    

        
        
services:
  app:
    build:
      context: .
      args:
        GREETING_NAME: World

Add GREETING_EMOJI to the build arguments to make the emoji available to the Dockerfile when Topo builds the application image:

    

        
        
services:
  app:
    build:
      context: .
      args:
        GREETING_NAME: World
        GREETING_EMOJI: "🐳"

Replace the hard-coded emoji in the web application

Open src/index.html, the HTML file used by the web application, in a text editor of your choice.

Find the line with the hard-coded emoji:

    

        
        
<span class="emoji floating">🐳</span>

Replace it with the GREETING_EMOJI variable from the Topo Project:

    

        
        
<span class="emoji floating">{{GREETING_EMOJI}}</span>

Topo replaces {{GREETING_EMOJI}} with the value provided during topo clone.

Update the Dockerfile

Open the Dockerfile, which is inside the topo-welcome directory. It currently defines GREETING_NAME as a build argument and uses sed to replace the {{GREETING_NAME}} placeholder:

    

        
        
ARG GREETING_NAME="World"

RUN sed -i "s|{{GREETING_NAME}}|${GREETING_NAME}|" /usr/share/nginx/html/index.html

Add a GREETING_EMOJI build argument, then add a second sed command to replace the {{GREETING_EMOJI}} placeholder:

    

        
        
FROM nginx:alpine

COPY src/index.html /usr/share/nginx/html/index.html

ARG GREETING_NAME="World"
ARG GREETING_EMOJI="🐳"

RUN sed -i "s|{{GREETING_NAME}}|${GREETING_NAME}|" /usr/share/nginx/html/index.html
RUN sed -i "s|{{GREETING_EMOJI}}|${GREETING_EMOJI}|" /usr/share/nginx/html/index.html

Clone the modified Topo Project

Create a new directory for a fresh clone of your modified local Topo Project:

    

        
        
mkdir -p ~/topo-new-welcome/

Clone the local project into the new directory:

    

        
        
topo clone dir:$(pwd) ~/topo-new-welcome/topo-welcome

Topo prompts for the configured project parameters. You’ll now see prompts for both GREETING_NAME and GREETING_EMOJI. Use the default value for GREETING_NAME and the example value for GREETING_EMOJI:

    

        
        ┌─ Copy files ──────────────────────────────────────────

┌─ Configure project ───────────────────────────────────
Provide: The text to use in the greeting message
Example: Markus
Default: World
GREETING_NAME (required)> 

Provide: The emoji to show next to the greeting
Example: 🚀
Default: 🐳
GREETING_EMOJI (optional)> 🚀

When cloning completes, Topo creates the new project in ~/topo-new-welcome/topo-welcome.

Deploy the modified Topo Project

Deploy the updated Topo Project to the target:

    

        
        
cd ~/topo-new-welcome/topo-welcome
topo deploy --target user@my-target

Visualize the application

If the target is reachable on your network, open http://<target-ip-address>:8000/ in your browser. You can also forward the port over SSH:

    

        
        
ssh -L 8000:localhost:8000 user@my-target

Then open http://localhost:8000/ in your browser.

The “Hello World” application appears as follows:

Image Alt Text:Screenshot of the modified Hello World web interface with a different emoji than the default. This confirms successful modification and deployment and provides a visual reference for the expected result.Hello World web interface - with new emoji argument

What you’ve accomplished and what’s next

You’ve now modified the “Hello World” Topo Project to add a new optional clone-time parameter, updated the Dockerfile to consume the argument, and deployed the result to your Arm-based Linux target.

Next, you’ll create a new Topo Project from scratch.

Back
Next