ui_poc/README.md

Dashboard UI

Table of Contents

• Introduction
• Deploy Locally
• Deploy Online
  • DNS Name
• Deploy on TFGrid with Full VM
  • Troubleshooting
• Deploy on TFGrid with Micro VM
  • Prepare the VM
  • Prepare Repo
  • Zinit
    • Manage Caddy with zinit
    • Manage Webserver with zinit
• Notes

---

Introduction

This is a proof-of-concept of a basic Dashboard UI in Python using FastApi and HTMX.

Deploy Locally

You can use the following script to deploy the UI locally.

# Clone the repository
git clone https://git.ourworld.tf/tfgrid/ui_poc
# Go to app directory
cd ui_poc/app
# Clean Up if necessary
rm -r venv
rm -r __pycache__
# Set Python environment
python3 -m venv venv
source venv/bin/activate
# Install requirements
python3 -m pip install -r requirements.txt
# Deploy the local website at port 8000
uvicorn app:app --reload

Deploy Online

You can deploy the webserver online with an IPv4 address. In this case make sure to set the DNS properly.

We show how to deploy online on both a micro and a full VM running on the TFGrid.

DNS Name

Set a DNS A record of your domain URL pointing to the IPv4 address.

Deploy on TFGrid with Full VM

You can deploy the website on the TFGrid. Follow those steps before after following the local steps.

• Deploy Full VM Ubuntu 24.04 with IPv4 address and connect into it via SSH
• Prepare the environment

  apt update && apt install -y git nano curl python3 python-is-python3 python3-venv python3-pip
  

• Install Caddy

  apt install -y debian-keyring debian-archive-keyring
  apt install -y apt-transport-https
  echo "deb [trusted=yes] https://releases.caddyserver.com/deb/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/caddy.list
  apt update
  apt install caddy
  

• Enable and start caddy

  systemctl enable caddy
  systemctl start caddy
  

• Create caddyfile at

  nano /etc/caddy/Caddyfile
  

• Caddyfile content

  example.com {
  	reverse_proxy 127.0.0.1:8000
  }
  

Troubleshooting

• Check the status

  systemctl status caddy
  

• Check the caddy log

  journalctl -u caddy
  

Deploy on TFGrid with Micro VM

You can deploy the website on the TFGrid with a micro VM.

Prepare the VM

• Deploy Micro VM Ubuntu 24.04 with IPv4 address and connect into it via SSH
• Prepare the environment

  apt update && apt install -y git nano curl python3 python-is-python3 python3-venv python3-pip
  

• Install Caddy

  apt install -y debian-keyring debian-archive-keyring
  apt install -y apt-transport-https
  echo "deb [trusted=yes] https://releases.caddyserver.com/deb/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/caddy.list
  apt update
  apt install caddy
  

Prepare Repo

We clone the repository.

# Clone the repository
cd /root
git clone https://git.ourworld.tf/tfgrid/ui_poc

Zinit

We manage Caddy and Uvicorn with Zinit.

Manage Caddy with zinit

We manage Caddy with zinit.

• Open the file for editing

  nano /etc/zinit/caddy.yaml
  

• Insert the following line with your own domain and save the file

  exec: caddy reverse-proxy --from example.com --to :8000
  

• Add the new Caddy file to zinit

  zinit monitor caddy
  

Zinit will start up Caddy immediately, restart it if it ever crashes, and start it up automatically after any reboots. Assuming you tested the Caddy invocation above and used the same form here, that should be all there is to it.

Here are some other Zinit commands that could be helpful to troubleshoot issues:

• See status of all services (same as "zinit list")

  zinit
  

• Get logs for a service

  zinit log caddy
  

• Restart a service (to test configuration changes, for example)

  zinit stop caddy
  zinit start caddy
  

• To forget a zinit service

  zinit forget caddy
  

Manage Webserver with zinit

We manage the webserver (uvicorn) with zinit.

• Create a script in /root/ui_poc/app

  #!/bin/bash
  
  cd /root/ui_poc/app
  rm -r venv
  rm -r __pycache__
  python3 -m venv venv
  source venv/bin/activate
  python3 -m pip install -r requirements.txt
  uvicorn main:app --reload
  

• Make the script executable

  chmod +x webserver.sh
  

• Open the file for editing

  nano /etc/zinit/webserver.yaml
  

• Insert the following line with your own domain and save the file

  exec: bash /root/ui_poc/app/webserver.sh
  

• Add the new Webserver file to zinit

  zinit monitor webserver
  

Notes

The .gitignore file is set with venv as the Python virtual environment.