RangePulse - Help

Overview

RangePulse is your personal health tracking app, running right on your Ubuntu system—like a private fitness journal you control. This guide makes setup a breeze, whether you're using a laptop, desktop, or even a Raspberry Pi.

You'll need a stable internet connection, about 500MB of free space, and your Ubuntu admin password. Our automated installer does the heavy lifting, and we'll guide you through each step with tips for success.

Think of this as setting up a new gadget—it's straightforward with the right instructions!

Supported Systems

RangePulse runs smoothly on a wide range of Ubuntu and Debian-based systems, including popular flavors and lightweight devices:

• Ubuntu 24.04.2 (and flavors like Kubuntu, Xubuntu)
• Ubuntu 22.04.5
• Debian 12.10.0 (Bookworm)
• Linux Mint 22.1 (Cinnamon, 64-bit)
• Zorin OS 17.3 (Core, 64-bit)
• Raspbian GNU/Linux 12 (Bookworm) on Raspberry Pi Zero W
• Raspbian GNU/Linux 11 (Bullseye) on Raspberry Pi Zero W

Even low-power devices like the Raspberry Pi Zero W (with just 512MB RAM) can handle RangePulse, making it perfect for budget-friendly or portable setups.

Installation

Setting up RangePulse on Ubuntu is like installing a new app—follow these steps to get started:

1. Purchase RangePulse: Head to rangepulse.com and buy RangePulse for $20 using our secure checkout. After payment, you'll land on a success page with your download instructions.
2. Copy the Installer Command: On the success page, look for the “Ubuntu Installer” section. You'll see a command like this (your token will be unique):

   curl -o installer_ubuntu.sh https://www.rangepulse.com/download/ubuntu?token=your-unique-token

   Note: This link expires in 72 hours.
3. Open Terminal: Find the Terminal app in your Ubuntu menu—it's like the control center for your system. Search for “Terminal” or “Konsole” if needed.
4. Choose a Folder: Pick a place to store the installer, like your home directory, by typing:

   cd ~

   Press Enter.
5. Download the Installer: Paste the copied curl command into Terminal and press Enter. This grabs the installer file, like downloading an app from a store.
6. Make It Ready: Allow the installer to run by typing:

   chmod +x installer_ubuntu.sh

   Press Enter.
7. Run the Installer: Launch the setup with admin access by typing:

   sudo bash installer_ubuntu.sh

   Enter your password when prompted. The installer sets everything up in 2-5 minutes, depending on your internet speed.
8. Check It Works: Open your web browser (like Firefox or Chrome) and visit http://localhost. You'll see the RangePulse homepage, ready to track your health stats!

Run into trouble? Jump to Troubleshooting or email hello@rangepulse.com. Keep your internet connected during setup. For a secure setup, see Enabling HTTPS and Authentication.

What Installation Does

The RangePulse installer sets up your Ubuntu system safely and efficiently. Here's what it adds to make your health tracker work:

All changes are standard and reversible, keeping your system tidy and secure.

Using RangePulse

RangePulse is your private dashboard for tracking health metrics. Here's how to use it:

1. Open RangePulse: In your browser, go to http://localhost (on the same computer) or http://your-computer's-ip (from another device on your network). For secure access, use https:// after enabling HTTPS (see Enabling HTTPS and Authentication). If authentication is enabled, enter your username and password (see Enabling HTTPS and Authentication).
2. Add Health Data: Enter weight, heart rate, blood pressure, or miles in the easy-to-use form (see the Data Entry Dashboard).
3. Track Progress: View charts and trends to see how you're doing over time (check out Health Trend Graphs).
4. Set Goals: Add personal targets for each metric to stay motivated (view the Fitness Goal Interface).
5. Export Data: Download your stats as a CSV file for backups or sharing with a doctor.

Find your computer's IP by typing ip addr show in Terminal. Look for a number like 192.168.x.x.

Maintenance

Keep RangePulse running like a well-oiled machine with these simple tasks:

• Check Activity Logs: See what's happening by typing tail -f rangepulse/rangepulse.log (exit with Ctrl+C).
• Manage Log Size: Check log size with ls -lh rangepulse/rangepulse.log. Clear it with > rangepulse/rangepulse.log if it grows too large.
• Back Up Your Data: Save your health stats with cp /home/user/rangepulse/rangepulse.db ~/backup.db.
• Check If It's Running: Type sudo systemctl status rangepulse and look for “active” in green.

Think of maintenance as tidying your desk—it keeps everything running smoothly.

Troubleshooting

Hit a snag? Try these beginner-friendly fixes for common RangePulse issues:

• Can't Open RangePulse: Check if it's running with sudo systemctl status rangepulse. Restart it with sudo systemctl restart rangepulse.
• Browser Says “Connection Refused”: Ensure port 80 is open by typing sudo ufw allow 80. For HTTPS, ensure port 443 is open with sudo ufw allow 443. Then retry http://localhost or https://localhost.
• Authentication Issues: If you enabled authentication and can't log in, verify your username and password. Reset the password file with sudo htpasswd -c /etc/apache2/.htpasswd rangepulse_user and ensure Apache is configured correctly (see Enabling HTTPS and Authentication).
• Setup Didn't Work: Confirm your internet connection and rerun sudo bash installer_ubuntu.sh.
• Error Messages: Look for clues in the logs with tail -f rangepulse/rangepulse.log. Search for words like “error” or “failed.” For HTTPS or authentication issues, check Apache logs with tail -f /var/log/apache2/rangepulse-ssl-error.log.

Still stuck? Email hello@rangepulse.com and share any error messages or logs from rangepulse.log or Apache logs.

Uninstallation

Ready to remove RangePulse? Follow these steps to cleanly uninstall:

1. Stop RangePulse: Type sudo systemctl stop rangepulse.
2. Prevent Auto-Start: Type sudo systemctl disable rangepulse.
3. Remove Service: Type sudo rm /etc/systemd/system/rangepulse.service.
4. Refresh System: Type sudo systemctl daemon-reload.
5. Delete App Files: Type rm -rf ./rangepulse ./rangepulse_venv.
6. Remove Settings: Type sudo rm /etc/rangepulse.env.
7. (Optional) Close Ports: Type sudo ufw delete allow 80 and sudo ufw delete allow 443.
8. (Optional) Delete Data: Type rm rangepulse/rangepulse.log rangepulse/rangepulse.db.
9. (Optional) Remove HTTPS Setup: If HTTPS was enabled, remove Apache with sudo apt purge -y apache2 and SSL files with sudo rm -rf /etc/ssl/rangepulse /etc/letsencrypt.
10. (Optional) Remove Authentication Setup: If authentication was enabled, remove the password file with sudo rm /etc/apache2/.htpasswd and Apache configurations with sudo rm /etc/apache2/sites-available/rangepulse-ssl.conf.

Before deleting, back up your health data with cp /home/user/rangepulse/rangepulse.db ~/backup.db to keep it safe.

Enabling HTTPS and Authentication

Secure your RangePulse installation with HTTPS and Apache Basic Authentication to encrypt data in transit and protect access with a username and password. These instructions guide you through setting up a secure web server on Ubuntu 24.04, using Apache to handle HTTP (port 80) and HTTPS (port 443), proxying to your Gunicorn application on port 8000, with a self-signed certificate and password protection for local use.

These steps require sudo privileges and familiarity with terminal commands. You will specify a server name and local domain name (e.g., server.local or rangepulse123.local) to create a temporary file (/tmp/servername.txt). Commands automatically insert this into configurations. Replace username with your Linux username (e.g., john) in commands.

Prerequisites

• Ubuntu 24.04 server with sudo privileges.
• RangePulse installed and running as a systemd service named rangepulse.service.
• A local .local domain (e.g., server.local) for network use.
• Access to edit /etc/hosts on client machines for external access.
• A terminal open on your server (preferably a console to avoid SSH issues).

Step 1: Specify Server Name

Define your server name and local domain name (e.g., server.local or rangepulse123.local) and create a temporary file for use in configurations.

SERVER_NAME="server.local" && echo "$SERVER_NAME" > /tmp/servername.txt

Replace server.local with your server name and local domain name (e.g., rangepulse123.local) before running the command. Ensure no spaces or special characters.

Verify:

• Run: cat /tmp/servername.txt
  Expect: Your server name and local domain name (e.g., server.local or rangepulse123.local).

If the file is empty or incorrect, re-run the command with the correct SERVER_NAME value (e.g., SERVER_NAME="rangepulse123.local" && echo "$SERVER_NAME" > /tmp/servername.txt).

Step 2: Stop Services and Check Ports

Stop RangePulse and unattended-upgrades to free port 80 and release package manager locks. Ensure ports 80 (Apache) and 8000 (Gunicorn) are free. Run commands one at a time to catch errors.

sudo systemctl stop rangepulse.service
sudo systemctl stop unattended-upgrades.service
sudo systemctl disable unattended-upgrades.service
# Retry killing unattended-upgrades processes
for i in {1..5}; do sudo kill -9 $(ps aux | grep -E '[u]nattended-upgr' | awk '{print $2}') 2>/dev/null || true; sleep 2; done
# Wait for package manager lock to release (up to 30 seconds)
for i in {1..6}; do if sudo lsof /var/lib/dpkg/lock-frontend | grep -q lock-frontend; then echo "Waiting for lock to release ($((i*5))s)..."; sleep 5; else echo "Lock released"; break; fi; done
sudo lsof /var/lib/dpkg/lock-frontend
sudo apt update
sudo ss -tuln | grep -E ":80 |:8000 "
sudo lsof -i :80
sudo lsof -i :8000

Verify:

• Run: sudo systemctl status rangepulse.service | grep "Active:"
  Expect: Active: inactive (dead).
• Run: sudo systemctl status unattended-upgrades.service | grep "Active:"
  Expect: Active: inactive (dead).
• Run: ps aux | grep -E '[u]nattended-upgr'
  Expect: No output (no running processes).
• Run: sudo lsof /var/lib/dpkg/lock-frontend
  Expect: No output (lock is free).
• sudo apt update should complete without lock errors, showing repository updates (e.g., Hit:1 http://security.ubuntu.com...).
• ss and lsof show no output for ports 80 and 8000 (ports free).

If the lock persists, wait 1-2 minutes and re-run. If still locked, identify the process (sudo lsof /var/lib/dpkg/lock-frontend), kill it (sudo kill -9 ), or reboot (sudo reboot). If ports are used, stop programs (sudo systemctl stop or sudo kill , avoid SSH PIDs). Verify SSH: sudo ss -tuln | grep ":22 ".

Step 3: Back Up and Update RangePulse Service

Back up the RangePulse service file and reconfigure Gunicorn to use port 8000 instead of 80.

sudo cp /etc/systemd/system/rangepulse.service /etc/systemd/system/rangepulse.service.bak
sudo nano /etc/systemd/system/rangepulse.service

Find the ExecStart= line and change the port from -b 0.0.0.0:80 to -b 0.0.0.0:8000. Save (Ctrl+O, Enter, Ctrl+X).

sudo systemctl daemon-reload
sudo systemctl restart rangepulse.service
sudo systemctl status rangepulse.service | grep "Active:"
sudo ss -tuln | grep ":8000 "

Verify:

• Run: ls /etc/systemd/system/rangepulse.service.bak
  Expect: /etc/systemd/system/rangepulse.service.bak.
• Run: grep '^ExecStart=' /etc/systemd/system/rangepulse.service
  Expect: Line with -b 0.0.0.0:8000.
• status shows: Active: active (running).
• ss shows a line with :8000.

If it fails, re-edit or restore backup (sudo mv /etc/systemd/system/rangepulse.service.bak /etc/systemd/system/rangepulse.service). Check logs (sudo journalctl -u rangepulse.service -n 50).

Step 4: Install Apache and Utilities

Install Apache, its utilities for authentication (htpasswd), and set up directories for logs and web content.

sudo apt update
sudo apt install -y apache2 apache2-utils
sudo systemctl stop apache2
sudo systemctl disable apache2
sudo mkdir -p /var/log/apache2 /var/www/html
sudo chown www-data:adm /var/log/apache2
sudo chown www-data:www-data /var/www/html
sudo chmod 750 /var/log/apache2
sudo chmod 755 /var/www/html

Verify:

• Run: apache2 -v
  Expect: Server version: Apache/2.x.x.
• Run: htpasswd -V
  Expect: htpasswd - Version x.x.x.
• Run: ls -ld /var/log/apache2 /var/www/html
  Expect: Directories with permissions (e.g., drwxr-x--- ... /var/log/apache2).
• Run: sudo systemctl status apache2 | grep "Active:"
  Expect: Active: inactive (dead).

If it fails, check internet (ping google.com) or disk space (df -h). If a lock error occurs, revisit Step 2.

Step 5: Create Certificate Directory

Create a directory for SSL certificate and key files.

sudo mkdir -p /etc/ssl/rangepulse
sudo chmod 755 /etc/ssl/rangepulse

Verify:

• Run: ls -ld /etc/ssl/rangepulse
  Expect: drwxr-xr-x ... /etc/ssl/rangepulse.

If it fails, check permissions (sudo ls -ld /etc/ssl) or disk space (df -h).

Step 6: Generate Self-Signed Certificate

Create a self-signed SSL certificate for HTTPS using the server name from the temporary file.

sudo sh -c 'echo "[req]\ndistinguished_name = req_distinguished_name\nx509_extensions = v3_req\nprompt = no\n[req_distinguished_name]\nC = US\nST = State\nL = City\nO = Organization\nOU = Unit\nCN = $(cat /tmp/servername.txt)\n[v3_req]\nbasicConstraints = critical,CA:FALSE\nsubjectAltName = DNS:$(cat /tmp/servername.txt)" > /tmp/openssl-san.cnf'

Verify configuration:

cat /tmp/openssl-san.cnf

Expect output with your server name and local domain name (e.g., CN = server.local or CN = rangepulse123.local and subjectAltName = DNS:server.local or subjectAltName = DNS:rangepulse123.local).

Generate certificate:

sudo sh -c 'openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/rangepulse/$(cat /tmp/servername.txt).key -out /etc/ssl/rangepulse/$(cat /tmp/servername.txt).crt -config /tmp/openssl-san.cnf && chmod 600 /etc/ssl/rangepulse/$(cat /tmp/servername.txt).key && chmod 644 /etc/ssl/rangepulse/$(cat /tmp/servername.txt).crt && rm /tmp/openssl-san.cnf'

Verify:

• Run: ls -l /etc/ssl/rangepulse/
  Expect: .crt, .key (with your server name and local domain name from /tmp/servername.txt, e.g., server.local.crt or rangepulse123.local.crt).
• Run: sudo sh -c 'openssl x509 -in /etc/ssl/rangepulse/$(cat /tmp/servername.txt).crt -text -noout | grep -E "Subject:|Subject Alternative Name"'
  Expect: Subject: C=US, ST=State, L=City, O=Organization, OU=Unit, CN= and Subject Alternative Name: DNS: (with your server name and local domain name, e.g., server.local or rangepulse123.local).

If it fails or files are missing, check openssl (sudo apt install openssl). Re-run commands carefully, ensuring no extra spaces. If errors persist, verify /tmp/servername.txt content from Step 1.

Step 7: Create and Manage Password File

Create a secure password file for user credentials. Replace rangepulse_user with your preferred username (e.g., admin).

sudo htpasswd -c /etc/apache2/.htpasswd rangepulse_user
sudo chown www-data:www-data /etc/apache2/.htpasswd
sudo chmod 640 /etc/apache2/.htpasswd

Enter a strong password when prompted.

To add another user:

sudo htpasswd /etc/apache2/.htpasswd another_user

To change a user's password (e.g., rangepulse_user):

sudo htpasswd /etc/apache2/.htpasswd rangepulse_user

Enter a new password when prompted.

To delete a user (e.g., rangepulse_user):

sudo htpasswd -D /etc/apache2/.htpasswd rangepulse_user

Verify:

• Run: ls -l /etc/apache2/.htpasswd
  Expect: -rw-r----- 1 www-data www-data with a non-zero file size.
• Run: sudo cat /etc/apache2/.htpasswd
  Expect: Lines with usernames (e.g., rangepulse_user:$apr1...) and hashed passwords. After deletion, the specified user should be absent.

Use -c only for the first user to create the file; omitting it preserves existing users. If the file is empty or permissions are wrong, recreate it or adjust permissions (sudo chown www-data:www-data /etc/apache2/.htpasswd). To verify password changes, test authentication in a browser.

Step 8: Configure Apache for HTTP-to-HTTPS Redirection and Authentication

Set up Apache to redirect HTTP to HTTPS, proxy to Gunicorn on 127.0.0.1:8000, and require authentication for HTTPS access, using the server name from the temporary file.

This configuration uses to scope authentication and proxy settings for URLs, not , as it's more appropriate for proxying to Gunicorn. The displayed code uses HTML entities (< and >) for browser rendering, but the command will generate a file with proper Apache syntax. Copy the command exactly to avoid syntax errors.

Create server name configuration:

sudo sh -c 'echo "ServerName $(cat /tmp/servername.txt)" > /etc/apache2/conf-available/servername.conf'

Create SSL site configuration with authentication. Copy the command below exactly as shown:

sudo sh -c 'cat > /etc/apache2/sites-available/rangepulse-ssl.conf <<'"'"'EOF'"'"' && sed -i "s/server.local/$(cat /tmp/servername.txt)/g" /etc/apache2/sites-available/rangepulse-ssl.conf
<VirtualHost *:80>
    ServerName server.local
    DocumentRoot /var/www/html
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [L,R=301]
    ErrorLog /var/log/apache2/rangepulse-http-error.log
    CustomLog /var/log/apache2/rangepulse-http-access.log combined
</VirtualHost>

<VirtualHost *:443>
    ServerName server.local
    DocumentRoot /var/www/html
    SSLEngine on
    SSLCertificateFile /etc/ssl/rangepulse/server.local.crt
    SSLCertificateKeyFile /etc/ssl/rangepulse/server.local.key
    <Location />
        AuthType Basic
        AuthName "Restricted Access"
        AuthUserFile /etc/apache2/.htpasswd
        Require valid-user
    </Location>
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8000/
    ProxyPassReverse / http://127.0.0.1:8000/
    ErrorLog /var/log/apache2/rangepulse-ssl-error.log
    CustomLog /var/log/apache2/rangepulse-ssl-access.log combined
    Header always set Strict-Transport-Security "max-age=31536000"
</VirtualHost>
EOF'

Update ports configuration:

sudo sh -c 'printf "Listen 80\nListen 443\n" > /etc/apache2/ports.conf'

Verify ports.conf:

cat /etc/apache2/ports.conf

Expect: Exactly Listen 80 and Listen 443 on separate lines, no other characters.

Enable configurations and modules:

sudo a2enconf servername
sudo a2dissite 000-default.conf
sudo a2ensite rangepulse-ssl.conf
sudo a2enmod ssl auth_basic authn_core authn_file authz_core authz_user proxy proxy_http rewrite headers
sudo apache2ctl configtest
sudo systemctl start apache2
sudo systemctl enable apache2

Verify:

• Run: cat /etc/apache2/sites-available/rangepulse-ssl.conf
  Expect: Configuration with raw <VirtualHost> and <Location /> tags (using actual < and > characters), your server name (e.g., server.local or rangepulse123.local), and AuthName "Restricted Access".
• Run: cat /etc/apache2/sites-available/rangepulse-ssl.conf | grep -E 'VirtualHost|Location'
  Expect: Lines starting with <VirtualHost and <Location.
• Run: apache2ctl configtest
  Expect: Syntax OK.
• Run: sudo systemctl status apache2 | grep "Active:"
  Expect: Active: active (running).
• Run: sudo a2query -m rewrite
  Expect: rewrite (enabled).
• Run: sudo a2query -m authn_file
  Expect: authn_file (enabled).
• In a browser, view this page: Expect the code block to display <VirtualHost *:80>, <VirtualHost *:443>, and <Location /> tags.

If it fails, check logs (sudo tail -n 20 /var/log/apache2/rangepulse-ssl-error.log) or configs (cat /etc/apache2/sites-available/rangepulse-ssl.conf, cat /etc/apache2/ports.conf). Ensure AuthName "Restricted Access" has no backslashes and authentication directives are within <Location />. If ports.conf contains invalid commands (e.g., -e), re-run the printf command. Ensure certificate files exist (ls -l /etc/ssl/rangepulse/).

Step 9: Restart RangePulse Service

Ensure RangePulse is running on port 8000.

sudo systemctl restart rangepulse.service
sudo systemctl status rangepulse.service | grep "Active:"

Verify:

• status shows: Active: active (running).

If it fails, check logs (sudo journalctl -u rangepulse.service -n 50) or restore backup.

Step 10: Configure Firewall, Re-enable Unattended Upgrades, and Test HTTPS

Allow HTTP (port 80) and HTTPS (port 443) traffic, restart unattended upgrades, test HTTP-to-HTTPS redirection with authentication, and clean up the temporary file.

sudo ufw allow 80
sudo ufw allow 443
sudo ufw status
sudo systemctl enable unattended-upgrades.service
sudo systemctl start unattended-upgrades.service
sudo sh -c 'curl -k -L -v http://$(cat /tmp/servername.txt)/health'
sudo sh -c 'curl -k https://$(cat /tmp/servername.txt)/health'
rm /tmp/servername.txt

Verify:

• ufw status shows:

  Status: active
  To                         Action      From
  --                         ------      ----
  22/tcp                     ALLOW       Anywhere
  80                         ALLOW       Anywhere
  443                        ALLOW       Anywhere
  [plus similar IPv6 rules]

• Run: sudo systemctl status unattended-upgrades.service | grep "Active:"
  Expect: Active: active (running) or similar.
• First curl (HTTP): Expect HTTP/1.1 301 Moved Permanently, Location: https:///health, final response HTTP/1.1 401 Unauthorized due to missing credentials (with your server name, e.g., server.local or rangepulse123.local).
• Second curl (HTTPS): Expect HTTP/1.1 401 Unauthorized.
• Test in a browser (http:// or https://): Expect a login prompt. Enter rangepulse_user and password to access.
• Run: ls /tmp/servername.txt
  Expect: No output (file removed).

If it fails, check Apache logs (sudo tail -n 20 /var/log/apache2/rangepulse-http-error.log) or modules (sudo a2enmod rewrite auth_basic authn_file authz_core authz_user). Reset password if needed (sudo htpasswd /etc/apache2/.htpasswd rangepulse_user). Ensure /etc/hosts resolves your domain.

Troubleshooting

Run these to diagnose issues:

sudo systemctl status apache2 | grep "Active:"
sudo systemctl status rangepulse.service | grep "Active:"
sudo apache2ctl configtest
sudo ss -tuln | grep -E ":80 |:443 |:8000 "
sudo tail -n 20 /var/log/apache2/rangepulse-ssl-error.log
sudo tail -n 20 /var/log/apache2/rangepulse-http-error.log
sudo ls -l /etc/apache2/.htpasswd
sudo journalctl -u rangepulse.service -n 50
sudo a2query -s
cat /etc/apache2/sites-available/rangepulse-ssl.conf | grep -E 'VirtualHost|Location'
cat /etc/apache2/sites-available/rangepulse-http.conf | grep -E 'VirtualHost|Location'

Common issues:

• No Redirect: Check logs (sudo tail -n 20 /var/log/apache2/rangepulse-http-error.log). Ensure rewrite module: sudo a2enmod rewrite && sudo systemctl restart apache2.
• No Login Prompt: Ensure modules: sudo a2enmod auth_basic authn_core authn_file authz_core authz_user && sudo systemctl restart apache2. Verify .htpasswd: ls -l /etc/apache2/.htpasswd. Check rangepulse-ssl.conf or rangepulse-http.conf for <Location /> using cat /etc/apache2/sites-available/rangepulse-*.conf.
• Incorrect Password: Reset: sudo htpasswd /etc/apache2/.htpasswd rangepulse_user.
• AuthType Error: Ensure authentication modules: sudo a2enmod auth_basic authn_core authn_file authz_core authz_user && sudo systemctl restart apache2. Check rangepulse-ssl.conf or rangepulse-http.conf for AuthType Basic within <Location /> using cat /etc/apache2/sites-available/rangepulse-*.conf.
• Incorrect Server Name: Verify /tmp/servername.txt: cat /tmp/servername.txt. If wrong, re-run Step 1 with the correct SERVER_NAME (e.g., SERVER_NAME="rangepulse123.local" && echo "$SERVER_NAME" > /tmp/servername.txt).
• Missing Configuration Tags: Check rangepulse-ssl.conf or rangepulse-http.conf: cat /etc/apache2/sites-available/rangepulse-*.conf | grep -E 'VirtualHost|Location'. Ensure they contain raw <VirtualHost> and <Location> tags (using actual < and > characters) with your server name. If missing, re-run the relevant command in Step 8 or Reverting Changes exactly as shown.
• Invalid Apache Syntax in Configuration Files: If apache2ctl configtest fails with errors like Invalid command '<VirtualHost', the configuration file contains HTML entities (< instead of <). Re-copy the command from this page exactly, or manually edit the file (sudo nano /etc/apache2/sites-available/rangepulse-ssl.conf or rangepulse-http.conf) to replace < with < and > with >.
• Wrong Configuration Edited: Check enabled sites: sudo a2query -s. If rangepulse-ssl is enabled, edit /etc/apache2/sites-available/rangepulse-ssl.conf. If rangepulse-http is enabled, edit /etc/apache2/sites-available/rangepulse-http.conf. Restart Apache: sudo systemctl restart apache2.
• SSL Errors: Verify certificate files (ls -l /etc/ssl/rangepulse/) and paths in rangepulse-ssl.conf. Ensure SSL module: sudo a2enmod ssl && sudo systemctl restart apache2. Re-run Step 6 if missing.
• DNS Issue: Verify /etc/hosts with ping (use your server name and local domain name).
• Certificate Warning: Trust the self-signed certificate in the browser.
• Port Conflict: Check ports: sudo ss -tuln | grep -E ":80 |:443 |:8000 ". Stop conflicting services or kill PIDs (avoid SSH PIDs).
• Syntax Errors: Verify configs (cat /etc/apache2/sites-available/rangepulse-*.conf, cat /etc/apache2/ports.conf) and test (sudo apache2ctl configtest). Ensure AuthName "Restricted Access" has no backslashes. If ports.conf contains invalid commands (e.g., -e), re-run the printf command in Step 8 or Reverting Changes.
• Permission Issues: Fix .htpasswd permissions: sudo chmod 640 /etc/apache2/.htpasswd.
• Lock Persists: Wait 1-2 minutes, re-run Step 2 commands, or kill lock process (sudo lsof /var/lib/dpkg/lock-frontend, sudo kill -9 ). Reboot if needed (sudo reboot).

If issues persist, test locally (curl http://localhost:80/health).

Reverting Changes

You can modify your setup to remove HTTPS, authentication, or both, in any order, or fully revert to the original HTTP setup without authentication. Choose the appropriate procedure below based on your needs.

1. Modify Configuration (Remove HTTPS and/or Authentication):

   This procedure allows you to remove HTTPS (switch to HTTP), remove Basic Authentication, or both, in any order. Follow the steps below based on your goal and the current state of your Apache configuration.

   Configurations use <Location /> to scope authentication and proxy settings for URLs, not <Directory>, as it's more appropriate for proxying to Gunicorn. The displayed code uses HTML entities (< and >) for browser rendering, but the command will generate a file with proper Apache syntax. Copy commands exactly to avoid syntax errors.

   Step A: Check Current Configuration

   First, determine whether Apache is serving HTTPS (rangepulse-ssl.conf) or HTTP (rangepulse-http.conf) and check listening ports.

   sudo a2query -s
   sudo ss -tuln | grep -E ":80 |:443 "
   sudo systemctl status apache2 | grep "Active:"

   Interpret the output:

   • If a2query -s shows rangepulse-ssl (enabled) and ss -tuln shows ports 80 and 443, Apache is serving HTTPS with HTTP-to-HTTPS redirection.
   • If a2query -s shows rangepulse-http (enabled) and ss -tuln shows only port 80, Apache is serving HTTP.
   • systemctl status should show Active: active (running).

   If no sites are enabled or Apache is not running, re-run Step 8 to restore rangepulse-ssl.conf.

   Step B: Remove Authentication (Keep Current Protocol)

   If you want to remove Basic Authentication (so no username/password prompt appears), edit the active configuration file to disable the authentication settings.

   Based on Step A:

   • If rangepulse-ssl is enabled (HTTPS): Edit rangepulse-ssl.conf.
   • If rangepulse-http is enabled (HTTP): Edit rangepulse-http.conf.

   Open the appropriate file:

   # For HTTPS (rangepulse-ssl.conf)
   sudo nano /etc/apache2/sites-available/rangepulse-ssl.conf
   # OR for HTTP (rangepulse-http.conf)
   sudo nano /etc/apache2/sites-available/rangepulse-http.conf

   Locate the <Location /> block (within <VirtualHost *:443> for rangepulse-ssl.conf, or <VirtualHost *:80> for rangepulse-http.conf). Comment out the entire block by adding # before each line:

   #<Location />
   #    AuthType Basic
   #    AuthName "Restricted Access"
   #    AuthUserFile /etc/apache2/.htpasswd
   #    Require valid-user
   #</Location>

   Save (Ctrl+O, Enter, Ctrl+X).

   Test and restart Apache:

   sudo apache2ctl configtest
   sudo systemctl restart apache2

   Verify:

   • Run: cat /etc/apache2/sites-available/rangepulse-ssl.conf or cat /etc/apache2/sites-available/rangepulse-http.conf
     Expect: The <Location /> block commented out (lines start with #).
   • Run: cat /etc/apache2/sites-available/rangepulse-*.conf | grep -E 'VirtualHost|Location'
     Expect: <VirtualHost> and commented <Location /> lines (with actual < and > characters).
   • Run: apache2ctl configtest
     Expect: Syntax OK.
   • Run: sudo systemctl status apache2 | grep "Active:"
     Expect: Active: active (running).
   • For HTTPS: Run: sudo sh -c 'curl -k https://$(cat /tmp/servername.txt)/health'
     Expect: HTTP/1.1 200 OK (no authentication prompt).
   • For HTTP: Run: sudo sh -c 'curl http://$(cat /tmp/servername.txt)/health'
     Expect: HTTP/1.1 200 OK (no authentication prompt).
   • Test in a browser (https:// or http://): Expect RangePulse access without a login prompt. For HTTPS, trust the self-signed certificate.

   If it fails, check logs (sudo tail -n 20 /var/log/apache2/rangepulse-ssl-error.log or rangepulse-http-error.log) or verify edits (cat /etc/apache2/sites-available/rangepulse-*.conf). Ensure only the <Location /> block is commented out. If you edited the wrong file, re-run Step A to confirm the active site.

   Step C: Remove HTTPS (Switch to HTTP)

   If you want to remove HTTPS and serve RangePulse over HTTP (with or without authentication), create or update rangepulse-http.conf and disable HTTPS settings.

   First, recreate the server name file (if it was removed in Step 10):

   SERVER_NAME="server.local" && echo "$SERVER_NAME" > /tmp/servername.txt

   Replace server.local with the server name used in Step 1 (e.g., rangepulse123.local). Ensure no spaces or special characters.

   Create rangepulse-http.conf. Choose the configuration based on whether you want to keep authentication:

   • With Authentication (username/password prompt):

   sudo sh -c 'cat > /etc/apache2/sites-available/rangepulse-http.conf <<'"'"'EOF'"'"' && sed -i "s/server.local/$(cat /tmp/servername.txt)/g" /etc/apache2/sites-available/rangepulse-http.conf
   <VirtualHost *:80>
       ServerName server.local
       DocumentRoot /var/www/html
       <Location />
           AuthType Basic
           AuthName "Restricted Access"
           AuthUserFile /etc/apache2/.htpasswd
           Require valid-user
       </Location>
       ProxyPreserveHost On
       ProxyPass / http://127.0.0.1:8000/
       ProxyPassReverse / http://127.0.0.1:8000/
       ErrorLog /var/log/apache2/rangepulse-http-error.log
       CustomLog /var/log/apache2/rangepulse-http-access.log combined
   </VirtualHost>
   EOF'

   • Without Authentication (no username/password prompt):

   sudo sh -c 'cat > /etc/apache2/sites-available/rangepulse-http.conf <<'"'"'EOF'"'"' && sed -i "s/server.local/$(cat /tmp/servername.txt)/g" /etc/apache2/sites-available/rangepulse-http.conf
   <VirtualHost *:80>
       ServerName server.local
       DocumentRoot /var/www/html
       ProxyPreserveHost On
       ProxyPass / http://127.0.0.1:8000/
       ProxyPassReverse / http://127.0.0.1:8000/
       ErrorLog /var/log/apache2/rangepulse-http-error.log
       CustomLog /var/log/apache2/rangepulse-http-access.log combined
   </VirtualHost>
   EOF'

   The commands above create /etc/apache2/sites-available/rangepulse-http.conf with your server name from /tmp/servername.txt (e.g., server.local or rangepulse123.local) replacing server.local.

   Update Apache configurations:

   sudo a2dissite rangepulse-ssl.conf
   sudo a2ensite rangepulse-http.conf
   sudo a2dismod ssl
   sudo sh -c 'printf "Listen 80\n" > /etc/apache2/ports.conf'

   Remove SSL certificates:

   sudo rm -rf /etc/ssl/rangepulse

   Update firewall rules:

   sudo ufw delete allow 443
   sudo ufw status

   Test and restart Apache:

   sudo apache2ctl configtest
   sudo systemctl restart apache2

   Verify:

   • Run: cat /tmp/servername.txt
     Expect: Your server name (e.g., server.local or rangepulse123.local).
   • Run: cat /etc/apache2/sites-available/rangepulse-http.conf
     Expect: A configuration with raw <VirtualHost *:80> block (using actual < and > characters), your server name, proxy settings, and (if chosen) a <Location /> block with authentication directives.
   • Run: cat /etc/apache2/sites-available/rangepulse-http.conf | grep -E 'VirtualHost|Location'
     Expect: Lines starting with <VirtualHost and (if authentication is enabled) <Location.
   • Run: cat /etc/apache2/ports.conf
     Expect: Listen 80 only.
   • Run: apache2ctl configtest
     Expect: Syntax OK.
   • Run: sudo systemctl status apache2 | grep "Active:"
     Expect: Active: active (running).
   • Run: sudo sh -c 'curl http://$(cat /tmp/servername.txt)/health'
     Expect: HTTP/1.1 401 Unauthorized (with authentication) or HTTP/1.1 200 OK (without authentication).
   • Test in a browser (http://): Expect a login prompt (with authentication) or direct access to RangePulse (without authentication).
   • In a browser, view this page: Expect the code blocks to display <VirtualHost *:80> and (for "With Authentication") <Location /> tags.
   • Run: ls /etc/ssl/rangepulse
     Expect: No output.
   • ufw status shows:

     Status: active
     To                         Action      From
     --                         ------      ----
     22/tcp                     ALLOW       Anywhere
     80                         ALLOW       Anywhere
     [plus similar IPv6 rules]

   If it fails, check logs (sudo tail -n 20 /var/log/apache2/rangepulse-http-error.log) or configs (cat /etc/apache2/sites-available/rangepulse-http.conf). Ensure authentication modules are enabled if needed (sudo a2enmod auth_basic authn_core authn_file authz_core authz_user). If HTTPS still responds, verify ports.conf and restart Apache.

   Step D: Combine Changes (Remove Both HTTPS and Authentication)

   If you want to remove both HTTPS and authentication, perform Step C and use the rangepulse-http.conf configuration without authentication. This creates an HTTP-only site without a login prompt in one step.

   You can perform Step B and Step C in any order. For example, remove authentication (Step B) while on HTTPS, then remove HTTPS (Step C), or vice versa. To revert to HTTPS, re-run Step 8. Always check the active site with sudo a2query -s before editing configurations.

2. Full Revert (Remove HTTPS and Authentication):

   Restore RangePulse to HTTP on port 80 without authentication, removing Apache and all configurations.

   Stop and disable Apache:

   sudo systemctl stop apache2
   sudo systemctl disable apache2
   sudo apt remove --purge -y apache2
   sudo rm -rf /etc/apache2 /var/log/apache2 /var/www/html

   Disable all sites:

   sudo a2dissite rangepulse-ssl.conf
   sudo a2dissite rangepulse-http.conf

   Restore RangePulse service:

   sudo mv /etc/systemd/system/rangepulse.service.bak /etc/systemd/system/rangepulse.service
   sudo systemctl daemon-reload
   sudo systemctl enable rangepulse.service
   sudo systemctl restart rangepulse.service

   Remove SSL certificates:

   sudo rm -rf /etc/ssl/rangepulse

   Remove temporary file:

   rm /tmp/servername.txt

   Revert firewall rule for HTTPS:

   sudo ufw delete allow 443
   sudo ufw status

   Verify:

   • Run: sudo systemctl status apache2 | grep "Active:"
     Expect: Active: inactive (dead) or service not found.
   • Run: ls /etc/apache2
     Expect: No output.
   • Run: grep '^ExecStart=' /etc/systemd/system/rangepulse.service
     Expect: -b 0.0.0.0:80.
   • Run: sudo systemctl status rangepulse.service | grep "Active:"
     Expect: Active: active (running).
   • Run: sudo ss -tuln | grep -E ":80 |:443 |:8000 "
     Expect: Only port 80 listed.
   • Run: curl http://$(cat /tmp/servername.txt)/health
     Expect: HTTP/1.1 200 OK.
   • Run: ls /etc/ssl/rangepulse
     Expect: No output.
   • Run: ls /tmp/servername.txt
     Expect: No output.
   • ufw status shows:

     Status: active
     To                         Action      From
     --                         ------      ----
     22/tcp                     ALLOW       Anywhere
     80                         ALLOW       Anywhere
     [plus similar IPv6 rules]

   If it fails, check logs (sudo journalctl -u rangepulse.service -n 50) or ensure the backup file exists (ls /etc/systemd/system/rangepulse.service.bak). Test locally (curl http://localhost:80/health).

Frequently Asked Questions

Got questions? Here are answers to common ones for Ubuntu users:

What's “sudo” and why do I need it?

It's a way to tell Ubuntu you're the boss, letting you make changes with your password.

Can I run RangePulse on my Ubuntu laptop?

Absolutely! It turns your laptop into a private health hub, no extra hardware needed.

Do I need internet after setup?

Only during setup to download tools. After that, RangePulse works offline on your system.

Is my health data safe?

Yes, it's stored only on your Ubuntu system. For extra security, enable HTTPS and authentication.

How do I find my computer's IP address?

Type ip addr show in Terminal, or use http://localhost (or https://localhost after enabling HTTPS).

What if my download link expires?

The link lasts 72 hours. Email hello@rangepulse.com for a new one.

Can I use RangePulse on a Raspberry Pi?

Yes, it runs great on Raspberry Pi models, even the Zero W!

Contact Support

Need assistance with RangePulse? Email hello@rangepulse.com or visit our main page. Please include:

• Your Ubuntu version (e.g., 24.04).
• What you're trying to do (e.g., install, access the app, enable HTTPS, or set up authentication).
• Any error messages or logs (e.g., from rangepulse.log or /var/log/apache2/rangepulse-ssl-error.log).

Replies may take a day—thanks for your patience!