Help & Support

Everything you need to get the most out of RangePulse.

1. Getting Started

RangePulse comes in two versions. Both include the same features: dashboard, charts, clinical PDF reports, data import/export, dark mode, and mobile support.

Cloud Quick Start

1. Sign up at rangepulse.com. Enter your email and choose a password.
2. Choose a plan. Monthly ($4.99/mo) or annual ($49/yr). Both include all features.
3. Add your first reading. From the dashboard, click the "+" button. Enter the date, your blood pressure, weight, heart rate, or mileage. Add optional notes (e.g., "after morning walk").
4. View your dashboard. Your chart appears after the first reading. Add more readings over the following days to see trends develop.

2. Self-Hosted Setup

Run RangePulse on your own server or computer. Your data never leaves your infrastructure. No account with us, no cloud dependency, no telemetry.

Requirements

• Docker and Docker Compose — if you don't have Docker installed yet, see the install guides below
• 512 MB RAM minimum (works on a Raspberry Pi Zero W)
• 500 MB free disk space (app + database; data grows ~1 MB per 1,000 readings)
• A web browser on the same network

Installing Docker (if you don't have it)

Install Docker first, then continue to the 5-step installation below.

Ubuntu / Debian / Raspberry Pi OS / Linux Mint:

curl -fsSL https://get.docker.com | sh

Fedora:

curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

RHEL / CentOS / AlmaLinux / Rocky Linux:

sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker

macOS: Download Docker Desktop for Mac. Skip Steps 1 and 2 below — Docker Desktop handles permissions and networking.

Windows: Download Docker Desktop for Windows (requires WSL2). Skip Steps 1 and 2 below.

Supported Systems

Any machine that runs Docker. Tested on:

• Ubuntu 22.04 LTS and 24.04 LTS
• Debian 12 (Bookworm)
• Raspberry Pi OS (Bookworm and Bullseye) — including Pi Zero W, Pi 3, Pi 4, Pi 5
• Fedora 39, 40, 41
• RHEL 9 / CentOS Stream 9 / AlmaLinux 9 / Rocky Linux 9
• Linux Mint 22
• Zorin OS 17
• Synology NAS (via Container Manager)
• Unraid (via Docker tab)
• macOS 13+ (Apple Silicon and Intel)
• Windows 10/11 with Docker Desktop or WSL2

Installation (Copy and Paste — 5 Steps)

These instructions are tested on Ubuntu 24.04. Run each step in order. Do not skip steps.

Step 1: Give your user permission to run Docker

This only needs to be done once. After running this command, you must log out completely and log back in before continuing to Step 2.

sudo usermod -aG docker $USER

Then log out (type exit or close your terminal), log back in, and verify it worked:

docker --version

If you see a version number (e.g., Docker version 27.x), continue. If you get "permission denied," you didn't log out and back in — do that now.

Step 2: Open port 80 in your firewall

Ubuntu / Debian:

sudo ufw allow 80/tcp
sudo ufw reload

Fedora / RHEL / CentOS / AlmaLinux:

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload

macOS / Windows with Docker Desktop: Skip this step — Docker Desktop handles networking automatically.

Step 3: Create the RangePulse folder and configuration file

Run this entire block — it creates a folder, enters it, and writes the configuration file:

mkdir -p ~/rangepulse && cd ~/rangepulse && cat > docker-compose.yml << 'EOF'
services:
  rangepulse:
    image: rangepulse/rangepulse:latest
    ports:
      - "80:8000"
    volumes:
      - rangepulse_data:/data
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    env_file:
      - .env

  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=86400
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LABEL_ENABLE=true
      - DOCKER_API_VERSION=1.45

volumes:
  rangepulse_data:
EOF

Step 4: Start RangePulse

Make sure you're in the rangepulse folder, then start it:

cd ~/rangepulse && docker compose up -d

If it's working, you'll see: Container rangepulse-rangepulse-1 Started

Wait about 10 seconds for the database to initialize on first startup.

Step 5: Open RangePulse in your browser

Go to http://localhost in your browser. You'll see the registration page. Create an account and start tracking your vitals.

Troubleshooting Installation

"Permission denied" when running docker compose:

• Did you run sudo usermod -aG docker $USER in Step 1?
• Did you log out and log back in after running it? This is required — the group change doesn't take effect until you start a new session.
• Quick workaround: prefix the command with sudo: sudo docker compose up -d

"Connection refused" or "This site can't be reached":

• Did you open port 80 in your firewall (Step 2)? This is the most common cause.
• Is the container actually running? Check with: cd ~/rangepulse && docker compose ps
• If the STATUS column says Restarting or Exited, check the logs: docker compose logs

"no configuration file provided: not found":

• You're not in the rangepulse folder. Run: cd ~/rangepulse first, then try again.

Port 80 already in use:

• If another service (Apache, Nginx) is using port 80, change the port in docker-compose.yml:

    ports:
      - "8080:8000"  # Use port 8080 instead

Then restart: cd ~/rangepulse && docker compose up -d

Access RangePulse at http://localhost:8080 instead.

To check what's using port 80: sudo lsof -i :80

Accessing from Another Device

To access RangePulse from your phone, tablet, or another computer on the same network:

1. Find your server's IP address:

   # Linux / macOS / Raspberry Pi:
   hostname -I
   # Look for something like 192.168.1.100

2. On your other device, open a browser and go to http://192.168.1.100:80 (replace with your actual IP).

Where Is My Data Stored?

All your health data is stored in a Docker volume called rangepulse_data. This persists across container restarts and updates. Your data is not inside the container — it's safe even if the container is deleted.

To see the volume location on disk:

docker volume inspect rangepulse_data

Updating to the Latest Version

Updates are automatic. Watchtower checks Docker Hub once a day and applies any new release silently — no action needed. Your Account page shows the current version and will note when a newer version is available and pending installation.

To update immediately without waiting for the daily check:

cd ~/rangepulse
docker compose pull
docker compose up -d

This pulls the latest image and restarts the container. Your data is in a Docker volume and is not affected.

Troubleshooting Updates

If the standard update does not work, use the steps below to diagnose and fix the issue.

Check whether the containers are running:

docker compose ps

You should see both rangepulse-rangepulse-1 and rangepulse-watchtower-1 with status Up. If either is missing or shows Restarting, see below.

Check what version is currently running:

docker exec rangepulse-rangepulse-1 grep APP_VERSION /srv/app.py

Check the application logs for errors:

docker logs rangepulse-rangepulse-1 --tail=50

If docker compose up -d fails with "container name already in use":
This happens when Watchtower has previously updated the container — Docker Compose loses track of it. Remove the old container and bring it back up:

docker rm -f rangepulse-rangepulse-1
docker compose up -d

If Watchtower is restarting repeatedly:

docker logs rangepulse-watchtower-1 --tail=30

Look for error messages at startup. The most common cause is a malformed docker-compose.yml. Compare your file against the template in Step 3 of the installation instructions above.

Full reset — stops everything, re-pulls the latest image, and starts fresh:
This does not delete your data. Your health data lives in the rangepulse_data Docker volume, which is preserved.

cd ~/rangepulse
docker compose down
docker compose pull
docker compose up -d

After running this, check that both containers are running:

docker compose ps

Both should show status Up (healthy) within 30 seconds.

If the app is up but you cannot log in after an update:
Your session cookie may have expired during the restart. This is normal — simply log in again with your username and password. Your data is intact.

Your data is preserved — it lives in the Docker volume, not the container image.

HTTPS Setup (Recommended for Remote Access)

RangePulse serves HTTP by default. If you access it outside your home network, you should add HTTPS. The easiest option is Caddy, which handles certificates automatically.

Caddy example — add this Caddyfile in the same directory:

health.yourdomain.com {
    reverse_proxy localhost:8000
}

Then add Caddy to your docker-compose.yml:

  caddy:
    image: caddy:latest
    ports:
      - "80:8000"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    restart: unless-stopped

Point your domain's DNS to your server's IP, and Caddy will automatically get a Let's Encrypt certificate.

Other options:

• Nginx + certbot — proxy_pass http://localhost:8000; in your server block, then run certbot --nginx.
• Traefik — add labels to your docker-compose service for automatic certificate management.
• Cloudflare Tunnel — zero-port-forwarding option if you don't want to open ports on your router.

Setting Up for Your Family

The self-hosted version supports unlimited accounts on one installation. Share the URL with your household and each person registers their own account. Every user's data is completely separate — users cannot see each other's readings, goals, or reports.

Example: you run RangePulse on a Raspberry Pi at http://192.168.1.100. Your spouse opens that URL on their phone, creates an account, and starts tracking their own blood pressure. Your daughter does the same. Three people, three separate dashboards, one server, zero monthly cost.

Admin Panel

The first user who registers is not automatically an admin. To enable the admin panel, add your email to the ADMIN_EMAILS environment variable in docker-compose.yml:

services:
  rangepulse:
    image: rangepulse/rangepulse:latest
    ports:
      - "80:8000"
    volumes:
      - rangepulse_data:/data
    environment:
      - ADMIN_EMAILS=you@example.com
    restart: unless-stopped

Then restart: docker compose up -d

The admin panel is at /admin/ and lets you:

• View all registered users
• See usage statistics (total readings, most active users)
• Delete accounts (for example, if someone in your household no longer uses it)

Password Reset (Self-Hosted)

The self-hosted version does not send emails, so the "Forgot Password" link will not work unless you configure an SMTP server. If you're locked out:

1. Access the database directly:

   docker exec -it rangepulse-rangepulse-1 \
     python3 -c "from auth import *; reset_password_cli('your@email.com', 'newpassword')"

2. Or delete and recreate your account (your data will be lost for that account).

Uninstalling

Stop RangePulse and keep your data (in case you want to come back):

docker compose down

Stop and permanently delete all data:

docker compose down -v

3. Dashboard Features

Adding Readings

Each reading can include any combination of the following:

• Blood pressure — systolic and diastolic (e.g., 128/82)
• Weight — in your preferred unit
• Heart rate — resting BPM
• Mileage — walking, running, or cycling distance
• Notes — free text for context (medication changes, illness, travel)

Fill in the form at the top of the dashboard and click Add Entry. The entry appears in your Recent Entries list immediately — no page reload. You can add, edit, delete, and restore entries without leaving the page.

On mobile, blood pressure fields are stacked (systolic on top, diastolic below) for easier entry with one thumb.

Goal Notifications

When you save a reading that hits a goal for the first time — for example, your blood pressure drops to or below your goal — a brief notification appears at the top of the screen confirming the achievement. It dismisses automatically after a few seconds.

Time Range Selection

Use the time range selector above the chart to change which period is displayed:

Chart Trend Lines

Each chart displays a trend line — a straight line calculated from your data points using linear regression. The trend line shows the overall direction of your readings over the selected time range.

• A downward trend on blood pressure or weight means your numbers are generally decreasing — often a positive sign.
• An upward trend on mileage means you are generally increasing your activity.
• A flat trend means your readings are stable.

Trend lines smooth out day-to-day variation so you can see the bigger picture.

Setting Goals

You can set a target goal for each metric (e.g., target weight, target blood pressure). Goals appear as a horizontal reference line on your chart so you can see at a glance how your readings compare to where you want to be.

4. Doctor Visit Report

What It Is

The "Prepare for Appointment" feature generates a clinical-quality PDF report summarizing your health data. The report includes statistical summaries, charts, AHA/ACC blood pressure classifications, trend arrows, and reading counts — designed to give your doctor the information they need at a glance.

How to Generate a Report

1. From the dashboard, click "Prepare for Appointment".
2. Select which metrics to include (blood pressure, weight, heart rate, mileage).
3. Choose a date range for the report.
4. Enter your name. This is printed on the report so your doctor can file it with your chart.
5. Click Generate. The PDF downloads to your device.

Print the PDF or email it to your doctor's office before your appointment.

What Your Doctor Sees

The report is formatted for clinical use:

• Name — displayed in LASTNAME, Firstname format, matching how most medical offices file records.
• Reading counts — shown as n= values (e.g., n=47) so your doctor knows how much data the statistics are based on.
• Trend arrows — visual indicators showing whether each metric is trending up, down, or stable over the selected period.
• BP classification — each blood pressure reading is categorized according to the AHA/ACC 2017 guidelines (Normal, Elevated, Stage 1, Stage 2).
• Summary statistics — averages, minimums, maximums, and standard deviations for each included metric.
• Charts — visual plots of your readings with trend lines.

5. Data Import & Export

Importing Data

You can import historical readings from a CSV file. The expected column format is:

date,weight,heart_rate,blood_pressure,mileage,notes

Example rows:

2026-01-15,182.4,72,128/82,3.2,Morning reading
2026-01-16,181.8,70,125/80,0,Rest day
2026-01-17,182.0,74,130/84,4.1,

• date — YYYY-MM-DD format.
• weight — numeric value in your preferred unit.
• heart_rate — beats per minute, whole number.
• blood_pressure — systolic/diastolic (e.g., 128/82).
• mileage — numeric distance.
• notes — free text (optional).

Leave any column blank if you do not have data for that metric on a given day. To import, go to the Data menu at the bottom of the dashboard and choose Import Data, then upload your CSV file.

Exporting Data

You can export all of your data at any time in two formats:

• CSV — a spreadsheet-compatible file using the same column format shown above.
• JSON — a structured data file, useful for developers or for migrating to another system.

Open the Data menu at the bottom of the dashboard and choose Export Data. Select CSV or JSON and the download begins immediately.

6. Trends and Insights

How Trend Calculations Work

RangePulse uses linear regression to calculate trend lines. This is a standard statistical method that finds the straight line that best fits your data points. It tells you the general direction of your readings over time, even when individual readings vary from day to day.

The trend line is recalculated every time you change the time range or add a new reading.

On mobile, changing the chart time range automatically updates the Trends & Insights period to match — you don't need to change both separately.

Blood Pressure Classification

RangePulse classifies each blood pressure reading according to the AHA/ACC 2017 guidelines:

The higher category always applies. For example, a reading of 135/92 is classified as Stage 2 because the diastolic value (92) falls in the Stage 2 range, even though the systolic value (135) is Stage 1.

Flagged Readings

A reading is flagged when it falls into the Stage 2 Hypertension range (140/90 or above). Flagged readings appear highlighted on your dashboard and are called out in the doctor visit report.

A flagged reading is a visual indicator that helps you and your doctor identify readings above the threshold where clinical guidelines recommend treatment. It is not an emergency alert.

7. Account Management

Changing Your Password

Go to Account → Change Password. Enter your current password and your new password. The change takes effect immediately.

Exporting Your Data

You can download all of your data at any time. Open the Data menu at the bottom of the dashboard and choose Export Data. Select CSV or JSON format. This works on both Cloud and self-hosted.

Deleting Entries

When you delete a reading from your dashboard, it's not permanently removed. Deleted entries go to a Recycle Bin where they're kept for 35 days.

• To delete: click the Delete button next to any entry on your dashboard
• To see deleted entries: open the Data menu → Recently Deleted
• To restore: click Restore next to any entry in the Recycle Bin
• After 35 days, deleted entries are permanently removed and cannot be recovered

Delete All Data — found in the Data menu — soft-deletes all your entries at once. A spinner appears in the entry list while the deletion is in progress. You can restore everything within 35 days using Restore All Data in the same menu.

Account deletion is different — deleting your account permanently removes everything immediately with no recovery period.

Cancelling Your Cloud Subscription

To cancel your Cloud subscription and close your account, visit app.rangepulse.com/cancel. You do not need to be logged in. Enter your email address and your Customer ID (e.g. RP-0123 — visible on your Account page) and submit.

• Your Stripe subscription is cancelled immediately — no further charges
• You have 3 days to log in and export your data
• After 3 days, your account and all health data are permanently deleted
• A confirmation email is sent with your deletion date and an export link

Deleting Your Account

To permanently delete your account and all associated data, go to your Account page and scroll to the bottom. Enter your password and click Delete My Account. A confirmation dialog will appear — confirm to proceed. This cannot be undone.

8. Maintenance (Self-Hosted)

Backing Up Your Data

RangePulse stores all data in a Docker volume. To back up:

docker compose stop
docker run --rm -v rangepulse_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/rangepulse-backup.tar.gz -C /data .
docker compose start

Store the resulting rangepulse-backup.tar.gz file somewhere safe.

Restoring from Backup

docker compose stop
docker run --rm -v rangepulse_data:/data -v $(pwd):/backup alpine \
  sh -c "rm -rf /data/* && tar xzf /backup/rangepulse-backup.tar.gz -C /data"
docker compose start

Viewing Logs

docker compose logs -f rangepulse

Press Ctrl+C to stop following the log output.

Checking Disk Usage

docker system df

Automatic Updates

RangePulse includes Watchtower in the default docker-compose.yml. Watchtower runs alongside the app and checks Docker Hub once a day for a new image. When one is available it pulls it, restarts the container, and cleans up the old image — fully automatic, no user action required.

Privacy: Watchtower only contacts Docker Hub to check the image digest and pull updates. It sends no user data, no health data, and no telemetry. It is scoped to the RangePulse container only and has no access to any other containers on your system.

To update immediately without waiting for the daily check, run:

docker compose pull && docker compose up -d

9. Troubleshooting

Container will not start

Check the logs for error messages:

docker compose logs rangepulse

Common causes:

• Port 80 already in use. Change the port mapping in docker-compose.yml (e.g., "3001:80").
• Docker not running. Start the Docker daemon: sudo systemctl start docker (Linux) or open Docker Desktop (macOS/Windows).
• Insufficient memory. RangePulse requires at least 512 MB RAM.

Cannot connect to localhost

• Verify the container is running: docker compose ps
• Check if the port is mapped correctly: docker compose port rangepulse 80
• If running on a remote server, connect to the server's IP address instead of localhost.

Data not appearing after import

• Verify your CSV uses the exact column headers: date,weight,heart_rate,blood_pressure,mileage,notes
• Check that dates are in YYYY-MM-DD format.
• Blood pressure must be in systolic/diastolic format (e.g., 128/82), not two separate columns.

PDF report not generating

• Make sure you have at least one reading in the selected date range.
• Check that your browser allows pop-ups or file downloads from the RangePulse domain.
• Try a different browser if the issue persists.

10. Frequently Asked Questions

11. Contact and Support

If you have a question, found a bug, or need help:

• Email: hello@rangepulse.com
• Self-hosted issues: Report bugs and feature requests on the RangePulse GitHub repository.

When emailing about a technical issue, please include:

• Which version you are using (Cloud or self-hosted)
• Your browser and device (e.g., Chrome on iPhone, Firefox on Windows)
• What happened and what you expected to happen
• A screenshot if possible