Deploying backend code - tuanchris/dune-weaver GitHub Wiki

There are two modes of deployment for backend code: Docker and Python script. If you are using any of the following supported devices, it is recommended to use Docker. Ensure that the OS is 64-bit.

Supported Devices

Raspberry Pi 3, 4, 5
Raspberry Pi Zero 2W
Any other PC/Mac (Python script deployment only)

Setting Up a Raspberry Pi

Setting up a Raspberry Pi should be straightforward. The recommended way is to use Raspberry Pi Imager.

Steps:

Download and install Raspberry Pi Imager.
Select your hardware, Raspberry Pi OS (64-bit), and your SD card.
Configure advanced options:
- Enable SSH
- Configure Wi-Fi credentials
Write the image to your SD card.

SSH into Your Raspberry Pi

SSH allows you to remotely access your Raspberry Pi for setup and maintenance.

Steps:

Insert the SD card into the Raspberry Pi and power it on.
You can connect to your Raspberry Pi using its hostname instead of an IP address. By default, you can use raspberrypi.local.
Open a terminal and connect via SSH:
```
ssh [email protected]
```
When prompted, enter the default password (raspberry) or the one you configured during setup.

Docker Deployment

Using Docker for deployment provides several advantages:

Automatic Restart: Services will restart after power outages.
Auto-Update Feature: Software can be updated directly from the browser.

Install Docker on Raspberry Pi

Update your system:
```
sudo apt update && sudo apt upgrade -y
```

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Add your user to the Docker group to run Docker without sudo:
```
sudo usermod -aG docker $USER
```
Important: You need to log out and log back in for the group changes to take effect.
```
exit
```
Then reconnect via SSH:
```
ssh pi@<your-pi-ip-address>
```
Verify Docker is installed correctly:
```
docker --version
```

Deploying Dune Weaver Using Docker Compose

Instead of manually running Docker commands, use the provided docker-compose.yml file to deploy Dune Weaver.

Clone the Dune Weaver repository:

git clone https://github.com/tuanchris/dune-weaver
cd dune-weaver

Run the service using Docker Compose:
```
docker compose up -d
```
Visit <raspberrypi_ip_address>:8080 and confirm that the backend is up. If this succeeds, you DO NOT need to deploy the Python backend below!

To stop the service:

docker compose down

This method ensures that all necessary dependencies and configurations are managed automatically.

Python Script Deployment

For devices that do not support Docker or if you prefer a manual setup, you can run the backend as a Python script. If you want the script to start automatically on boot, follow the instructions below.

One-Time Running of the Script

If you want to run the script manually without setting it up to start on boot, use the following commands:

Clone and change directory:

git clone https://github.com/tuanchris/dune-weaver
cd dune-weaver

Install Python virtual environment:
```
sudo apt install python3-venv
```

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```
Run the application:
```
python app.py
```

Start the Script on Boot (Linux based system)

To ensure the script runs on startup, create a systemd service. If you change your username, substitute yours for pi below.

Create a new service file:

sudo nano /etc/systemd/system/dune-weaver.service

Add the following content:

[Unit]
Description=Dune Weaver Backend
After=network.target

[Service]
ExecStart=/home/pi/dune-weaver/.venv/bin/python /home/pi/dune-weaver/app.py
WorkingDirectory=/home/pi/dune-weaver
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

Save the file and reload systemd:
```
sudo systemctl daemon-reload
```

Enable and start the service:

sudo systemctl enable dune-weaver
sudo systemctl start dune-weaver

To check the status of the service:
```
sudo systemctl status dune-weaver
```

If you see Failed to start dune-weaver.service - Dune Weaver Backend., chances are you deployed the Docker backend first, so the Python backend cannot start on the same port 8080. You only need to deploy Docker or Python!

Accessing the Web UI

Open up a browser on your phone or on your computer to access the web UI.

If you run your backend on your computer, you can access the UI by going to localhost:8080.
If deployed onto a raspberry pi, the address should be raspberry.local:8080 or <raspberrypi_ip_address>:8080

Troubleshooting

Check Docker Logs

If you encounter issues with the Docker deployment, check the logs:

docker compose logs -f