Ate toaster 20250717

debian/conffiles

@@ -0,0 +1,3 @@
+/etc/randao/.env
+/etc/randao/wallet.json
+/etc/randao/wallet.seed

debian/etc/systemd/system/randao.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=RANDAO Provider
+# When running manually, use the --no-block flag:
+# 	systemctl start --no-block randao.service
+Requires=docker.service
+After=docker.service
+#Wants-randao.timer
+
+[Service]
+Type=simple
+User=randao_service
+Group=randao_service
+WorkingDirectory=/home/randao/RandaoProvider/docker-compose
+#ExecStart=/usr/bin/docker compose --env-file /etc/randao/.env up --pull=always
+ExecStart=/usr/bin/docker compose -f docker-compose.yml -f docker-compose.appliance.yml --env-file /etc/randao/.env up --pull=always
+ExecStop=/usr/bin/docker compose down
+TimeoutStartSec=0
+Restart=on-failure
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target

debian/etc/systemd/system/randao.timer

@@ -0,0 +1,22 @@
+Description=Timer to periodically restart RANDAO Provider for latest image pull
+#Requires=randao.service
+#After=randao.service
+
+[Timer]
+# Restart every day at a random time within the first hour of the day
+# OnCalendar=daily
+# RandomizedDelaySec=1h
+# Persistent=true
+
+# OR, restart every 12 hours (e.g., 00:00, 12:00) with a random delay
+OnCalendar=*-*-* 00,12:00:00
+RandomizedDelaySec=30min
+Persistent=true
+
+# OR, restart every 8 hours from when the service last became active
+#OnUnitActiveSec=8h
+#RandomizedDelaySec=30min
+#AccuracySec=1min # Optional: Reduce timer inaccuracy from default (often 1min)
+
+[Install]
+WantedBy=timers.target

debian/etc/update-motd.d/66-randao

@@ -0,0 +1,59 @@
+#!/bin/bash
+THIS_SCRIPT="randao"
+MOTD_DISABLE=""
+
+[[ -f /etc/default/armbian-motd ]] && . /etc/default/armbian-motd
+
+for f in $MOTD_DISABLE; do
+	[[ $f == $THIS_SCRIPT ]] && exit 0
+done
+
+## FORMATTING VARIABLES
+# --- ANSI Color Codes ---
+RED=$'\e[31m'
+GREEN=$'\e[32m'
+BLUE=$'\e[94m'
+YELLOW=$'\e[93m'
+GOLD=$'\e[38;5;214m'
+ORANGE=$'\e[38;5;208m'
+MAGENTA=$'\e[35m'
+CYAN=$'\e[36m'
+
+# if using color with effects, use color first and then the effect. The color codes above reset the effect to none.
+BOLD=$'\e[1m' # bold 
+ITAL=$'\e[3m' # italics
+ULINE=$'\e[4m' # underline
+XOUT=$'\e[9m' # crossed out
+REV=$'\e[7m' # reversed
+NC=$'\e[0m' # No Color (resets to default)
+
+
+#servicelist=("randao.service" "randao.timer")
+servicelist=("randao.timer")
+
+for service in "${servicelist[@]}"; do
+	if [[ -f "/etc/systemd/system/${service}" ]]; then
+		serviceEnabled=$(systemctl is-enabled $service)
+		if [[ ${serviceEnabled} == "enabled" ]]; then
+			serviceEnabled="${BOLD}${GREEN}enabled${NC}"
+            		serviceMessage=""
+		else
+			serviceEnabled="${BOLD}${YELLOW}disabled${NC}"
+            		serviceMessage="To enable ${BOLD}${service}${NC}: sudo systemctl enable ${service}"
+        	fi
+
+        	serviceActive=$(systemctl is-active $service)
+		if [[ ${serviceActive} == "active" ]]; then
+			# service is active
+			serviceActive="${BOLD}${GREEN}active${NC}"
+		            serviceMessage+=""
+		else
+			# service is in-active
+			serviceActive="${BOLD}${YELLOW}inactive${NC}"
+		        serviceMessage+="\nThen start ${BOLD}${service}${NC}: sudo systemctl start ${service}"
+        fi
+
+		echo -e "${BOLD}${service} is $serviceEnabled and $serviceActive."
+		echo -e "${serviceMessage}\n"
+    fi
+done

debian/install

@@ -0,0 +1,15 @@
+# Source files from your Git repo (relative to repo root)  
+# Destination on target system (relative to /)
+
+# Systemd service and timer files
+debian/etc/systemd/system/randao.service        /etc/systemd/system/
+debian/etc/systemd/system/randao.timer          /etc/systemd/system/
+debian/etc/update-motd.d/66-randao              /etc/update-motd.d/66-randao
+
+# Docker Compose project files
+docker-compose/                                 /opt/randao-provider/
+orchestrator/                                   /opt/randao-provider/
+puzzle-generator/                             /opt/randao-provider/
+requester/                                    /opt/randao-provider/
+LICENSE                                       /opt/randao-provider/
+README.md                                     /opt/randao-provider/

debian/postinst

@@ -0,0 +1,99 @@
+#!/bin/sh
+# postinst script for randao-provider Debian package
+
+set -e # Exit immediately if a command exits with a non-zero status
+
+# --- 1. Define Paths and Logging ---
+LOG_FILE="/var/log/randao-provider-postinst.log"
+USERNAME="randao_service"
+GROUPNAME="randao_service"
+DOCKER_GROUP="docker"
+ETC_RANDAO_DIR="/etc/randao"
+APP_ROOT_DIR="/opt/randao-provider"
+
+# Initialize log file with secure permissions
+touch "$LOG_FILE"
+chmod 600 "$LOG_FILE"
+
+log_message() {
+    echo "$(date '+%Y-%m-%d %H:%M:%S') - postinst: $1" >> "$LOG_FILE"
+}
+
+log_message "Starting randao-provider post-installation script."
+
+# --- 2. Create the dedicated system user and group ---
+log_message "Checking for user '$USERNAME' and group '$GROUPNAME'."
+if ! id -u "$USERNAME" >/dev/null 2>&1; then
+    log_message "Creating system user '$USERNAME' with a dynamic UID."
+    # Let the system pick a safe UID automatically
+    adduser --system --no-create-home --group "$USERNAME"
+    log_message "User '$USERNAME' created."
+else
+    log_message "User '$USERNAME' already exists. Skipping creation."
+fi
+
+# Add the user to the docker group if it exists
+if getent group "$DOCKER_GROUP" >/dev/null 2>&1; then
+    if ! getent group "$DOCKER_GROUP" | grep -q "\b$USERNAME\b"; then
+        log_message "Adding user '$USERNAME' to group '$DOCKER_GROUP'."
+        usermod -aG "$DOCKER_GROUP" "$USERNAME"
+        log_message "User '$USERNAME' added to '$DOCKER_GROUP'."
+    else
+        log_message "User '$USERNAME' is already in group '$DOCKER_GROUP'."
+    fi
+else
+    log_message "WARNING: Group '$DOCKER_GROUP' does not exist. The service may not function correctly."
+fi
+
+# --- 3. Manage Configuration ---
+# NOTE: This section is ideally replaced by using a 'conffiles' file.
+# The logic is kept here assuming you are not using conffiles yet.
+log_message "Ensuring config directory '$ETC_RANDAO_DIR' exists."
+mkdir -p "$ETC_RANDAO_DIR"
+chown root:root "$ETC_RANDAO_DIR"
+chmod 700 "$ETC_RANDAO_DIR" # Only root can access the directory listing
+
+TEMPLATE_DIR="$APP_ROOT_DIR/docker-compose/templates"
+
+# Safely copy example config files if they don't already exist
+if [ ! -f "$ETC_RANDAO_DIR/.env" ]; then
+    log_message "Copying example.env to $ETC_RANDAO_DIR/.env."
+    cp "$TEMPLATE_DIR/example.env" "$ETC_RANDAO_DIR/.env"
+fi
+if [ ! -f "$ETC_RANDAO_DIR/wallet.json" ]; then
+    log_message "Copying example.wallet.json to $ETC_RANDAO_DIR/wallet.json."
+    cp "$TEMPLATE_DIR/example.wallet.json" "$ETC_RANDAO_DIR/wallet.json"
+fi
+
+# --- 4. Set Secure Permissions for Configuration Files ---
+# Set permissions on any config file that exists in the directory.
+log_message "Setting ownership and permissions for config files in '$ETC_RANDAO_DIR'."
+if [ -f "$ETC_RANDAO_DIR/.env" ]; then
+    chown root:"$GROUPNAME" "$ETC_RANDAO_DIR/.env"
+    chmod 640 "$ETC_RANDAO_DIR/.env" # root:rw, group:r, other:---
+fi
+if [ -f "$ETC_RANDAO_DIR/wallet.json" ]; then
+    chown root:"$GROUPNAME" "$ETC_RANDAO_DIR/wallet.json"
+    chmod 640 "$ETC_RANDAO_DIR/wallet.json"
+fi
+if [ -f "$ETC_RANDAO_DIR/wallet.seed" ]; then
+    chown root:"$GROUPNAME" "$ETC_RANDAO_DIR/wallet.seed"
+    chmod 640 "$ETC_RANDAO_DIR/wallet.seed"
+fi
+
+log_message "Permissions set. User '$USERNAME' (in group '$GROUPNAME') has read-access to configs."
+log_message "IMPORTANT: Remember to edit configuration in /etc/randao/ with your actual secrets."
+
+# --- 5. Enable and Start Systemd Units ---
+# NOTE: This section is ideally removed in favor of deb-helper in debian/rules.
+# The logic is kept here assuming you are not using deb-helper yet.
+log_message "Reloading systemd daemon, then enabling and starting randao.timer."
+systemctl daemon-reload
+systemctl enable randao.timer
+systemctl start --no-block randao.timer
+log_message "Systemd randao.timer has been enabled and started."
+
+
+log_message "Randao Provider post-installation script finished."
+
+exit 0

debian/rules

@@ -0,0 +1,10 @@
+#!/usr/bin/make -f
+
+%:
+	dh $@
+
+# This block overrides the default 'dh_auto_configure' step.
+# It tells deb-helper to run the 'configure' script but with
+# an extra option. After this step, the normal sequence continues.
+override_dh_auto_configure:
+	dh_auto_configure -- --with-extra-feature

docker-compose/.env.example

@@ -3,15 +3,8 @@ DB_PASSWORD=mypassword
 DB_NAME=mydatabase
 DOCKER_NETWORK=backend
 LOG_CONSOLE_LEVEL=3
-SEED_PHRASE="Create a NEW wallet and enter the 12 - 24 words here"
-WALLET_JSON = '{
-  "kty": "RSA",
-  "e": "test",
-  "n": "test",
-  "d": "test",
-  "p": "test",
-  "q": "test",
-  "dp": "test",
-  "dq": "test",
-  "qi": "test"
-}'
+## Enable ONE of the wallet methods below:
+#SEED_FILE_PATH=/app/config/wallet.seed # path corresponds to the container volume mounted in docker-compose.yml file
+#WALLET_JSON_FILE_PATH=/app/config/wallet.json # path corresponds to the container volume mounted in docker-compose.yml file
+#SEED_PHRASE="Create a NEW wallet and enter the 12 - 24 words here"
+#WALLET_JSON = '{  "kty": "RSA",   "e": "test",   "n": "test",   "d": "test",   "p": "test",   "q": "test",   "dp": "test",   "dq": "test",   "qi": "test" }'

docker-compose/QuickStart.md

@@ -0,0 +1,104 @@
+# **Randao Provider: Quick Start Guide**
+
+This guide provides a quick way to get the Randao Provider running on your local machine using Docker Compose. This is ideal for development, testing, or non-appliance deployments.  
+**Assumptions:**
+
+- You have **Docker Desktop** (Windows/macOS) or **Docker Engine** (Linux) installed and running.
+- You have basic command-line knowledge.
+- You are using the official randao/orchestrator image, which has been pre-built with the necessary wallet management modifications.
+- **You have a compatible Arweave wallet (JWK file or mnemonic seed phrase) ready.**
+
+## **1\. Get the Project Files**
+
+First, clone the Randao Provider repository from GitHub:
+```sh
+git clone https://github.com/RandAOLabs/Randomness-Provider.git randao-provider
+```
+
+Now, navigate into the Docker Compose directory:  
+``sh
+cd randao-provider/docker-compose/
+``
+
+## **2\. Prepare Configuration Files**
+
+You need to create/edit two essential configuration files: .env (for database and logging) and your wallet key file (wallet.json or wallet.seed).
+
+### **2.1. Create .env (Environment Variables)**
+
+This file stores your database credentials and other settings.
+
+1. Copy the example .env file:  
+  cp .env.example .env
+
+2. Open the newly created .env file in a text editor (e.g., nano .env or code .env) and **fill in your desired values** for the database user, password, and name. You can keep the defaults if running locally for testing.  
+  \# .env  
+  DB\_USER=myuser  
+  DB\_PASSWORD=mypassword  
+  DB\_NAME=mydatabase  
+  DOCKER\_NETWORK=backend  
+  LOG\_CONSOLE\_LEVEL=3 \# Set to 7 for verbose (DEBUG) logs
+
+
+### **2.2. Create Wallet Key File (wallet.json or wallet.seed)**
+
+This file contains your Arweave wallet's private key (JWK) or mnemonic seed phrase. The application will prioritize reading from wallet.json (JWK) if both are present. If neither file is found, it will fall back to environment variables. We recommend using Wander as the Chrome plugin integrates easily with our [Provider Portal](https://providers_randao.ar.io/providers). 
+
+#### **Option A: Using wallet.json (JWK)**
+
+1. Copy the example wallet.json file:  
+  cp wallet.json.example wallet.json
+
+2. Open wallet.json in a text editor and **replace its content with your actual Arweave wallet's JWK (JSON Web Key) data.**  
+  **⚠️ IMPORTANT SECURITY WARNING ⚠️**
+
+  - **NEVER use the example wallet content for a real wallet.** Always generate your own unique Arweave wallet.
+  - **Keep your wallet.json file secure.** Do not share it or commit it to public repositories.
+  - On Linux/macOS, it is highly recommended to set strict permissions:  
+    chmod 600 wallet.json
+
+#### **Option B: Using wallet.seed (Mnemonic Seed Phrase)**
+
+1. Copy the example wallet.seed file:  
+  cp wallet.seed.example wallet.seed
+
+2. Open wallet.seed in a text editor and **replace its content with your actual Arweave wallet's mnemonic seed phrase.** The seed phrase must be 12, 18, or 24 words, separated by single spaces, with no extra characters.  
+  **⚠️ IMPORTANT SECURITY WARNING ⚠️**
+
+  - **NEVER use the example seed phrase for a real wallet.** Always generate your own unique Arweave wallet.
+  - **Keep your wallet.seed file secure.** Do not share it or commit it to public repositories.
+  - On Linux/macOS, it is highly recommended to set strict permissions:  
+    chmod 600 wallet.seed
+
+### **2.3. Alternative (Less Secure Fallback): Environment Variables**
+
+If you prefer not to create wallet.json or wallet.seed files, you can instead add the wallet content directly into your .env file using the WALLET\_JSON or SEED\_PHRASE environment variables. The application will fall back to these if it cannot read from the mounted files.
+
+- **For JWK:** Add WALLET\_JSON='{"your\_jwk\_content\_here"}' to your .env file.
+- **For Seed Phrase:** Add SEED\_PHRASE="your seed phrase words here" to your .env file.
+
+However, **this method is less secure as environment variables are easily inspectable.**
+
+## **3\. Run the Randao Provider**
+
+Now you can start your Docker Compose stack. This command will automatically pull the necessary Docker images and set up your services.  
+docker compose up \-d \--pull=always
+
+- \--pull=always: Ensures that Docker always checks for and pulls the latest versions of the images from Docker Hub.
+- up: Starts the services in the foreground, showing their logs directly in your terminal.
+- \-d: run the container in the background (detached mode)
+
+
+## **4\. Monitor Logs**
+
+To see the real-time output from your running services (especially for debugging wallet initialization):
+
+`docker compose logs \-f`
+
+## **5\. Stop the Randao Provider**
+
+To stop and remove the running containers, networks, and volumes (excluding named volumes like pgdata):
+
+`docker compose down`
+
+You should now have your Randao Provider up and running locally\!

docker-compose/docker-compose.appliance.yml

@@ -0,0 +1,28 @@
+# /home/randao/Randomness-Provider.git/docker-compose/docker-compose.appliance.yml
+services:
+  orchestrator:
+    volumes:
+      # Override wallet mounts to point to /etc/randao/ for appliance security
+      - /etc/randao/wallet.json:/app/config/wallet.json:ro
+      - /etc/randao/wallet.seed:/app/config/wallet.seed:ro # If used
+    deploy: # Appliance-specific orchestrator deploy rules
+      resources:
+        limits:
+          cpus: '1.5'   # Allow orchestrator up to 1.5 cores
+          memory: 300M  # Allow up to 300MB RAM
+        reservations:
+          cpus: '0.5'   # Reserve 0.5 of a core
+          memory: 192M
+
+  postgres: # Appliance-specific postgres deploy rules and config mount
+    volumes:
+      - ./postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro # <--- ADDED HERE
+    shm_size: '64m' # <--- ADDED HERE (or adjust as needed)
+    deploy:
+      resources:
+        limits:
+          cpus: '0.4'   # Limit Postgres to 40% of one core
+          memory: 150M  # Limit Postgres to 150MB RAM
+        reservations:
+          cpus: '0.1'   # Reserve 10% of one core
+          memory: 64M