Help & Support

Everything you need to get the most out of RangePulse.

1. Getting Started

RangePulse comes in two versions: Cloud (we host it for you) and Self-Hosted (free — you run it on your own server with Docker). Cloud has three plans:

Every paid plan has a 30-day money-back guarantee, and it's self-serve — one click on your Account page refunds your latest payment instantly. See Refunds.

Cloud Quick Start

1. Sign up at app.rangepulse.com/register. Enter your email and choose a password.
2. Verify your email. We send you a verification link — click it. You can start tracking right away, but you must verify your email before you can upgrade to a paid plan.
3. Choose a plan. Start on the Free plan, or upgrade from your Account page: Solo ($4.99/mo or $39.99/yr) or Family ($7.99/mo or $69.99/yr, up to 5 people).
4. 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").
5. 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 health data never leaves your infrastructure — no account with us, no telemetry. (The app does check for updates; see "What talks to the internet?" below for the honest details.)

Requirements

• An amd64 (Intel/AMD 64-bit) machine. This is the only supported architecture — see Supported Systems below.
• Docker and Docker Compose — if you don't have Docker installed yet, see the install guides below
• 512 MB RAM minimum
• 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 / 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 (Intel): Download Docker Desktop for Mac. Skip Step 1 below — Docker Desktop handles permissions.

Windows: Download Docker Desktop for Windows (requires WSL2). Skip Step 1 below.

Supported Systems

The RangePulse Docker image is built for amd64 (Intel/AMD 64-bit) only. Tested on:

• Ubuntu 22.04 LTS and 24.04 LTS
• Debian 12 (Bookworm)
• Fedora 39, 40, 41
• RHEL 9 / CentOS Stream 9 / AlmaLinux 9 / Rocky Linux 9
• Linux Mint 22 and Zorin OS 17
• Synology NAS with an Intel/AMD processor (via Container Manager)
• Unraid (via Docker tab)
• macOS 13+ on Intel Macs (Docker Desktop)
• Windows 10/11 with Docker Desktop or WSL2

Not supported: Raspberry Pi (all models) and other ARM devices — the image will not run on them. Apple Silicon Macs are also unsupported; Docker Desktop may run the image under emulation, but we do not test or support that.

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. (macOS / Windows with Docker Desktop: skip this step.)

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: 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 3: Create the settings file

The configuration above tells Docker to read settings from a file named .env. Docker Compose refuses to start if this file doesn't exist — even though it's perfectly fine for it to be empty. Create it:

cd ~/rangepulse && touch .env

An empty .env is normal. Every setting is optional — later, optional settings like ADMIN_EMAILS (see Admin Panel below) go in this file.

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

"env file ... not found" when starting:

• You skipped Step 3 — this is the most common fresh-install failure. Run cd ~/rangepulse && touch .env and start again. An empty .env is fine.

"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":

• 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
• If you changed the port mapping, make sure you're using the right port in your browser (e.g., http://localhost:8080).

"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 first number of the port mapping in docker-compose.yml. The second number must stay 8000 — that's the port the app listens on inside the container:

    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:
   hostname -I
   # macOS:
   ipconfig getifaddr en0
   # Windows (look for "IPv4 Address"):
   ipconfig

   Look for something like 192.168.1.100.

2. On your other device, open a browser and go to http://192.168.1.100 (replace with your actual IP; add :8080 if you changed the port).

Where Is My Data Stored?

All your health data is stored in a Docker volume. In the compose file the volume is named rangepulse_data, but Docker prefixes volume names with the folder name — so with the standard ~/rangepulse folder, the real name on disk is rangepulse_rangepulse_data. You can confirm yours with:

docker volume ls

To see the volume location on disk:

docker volume inspect rangepulse_rangepulse_data

This volume persists across container restarts and updates. Your data is not inside the container — it's safe even if the container is deleted.

Updating to the Latest Version

Updates are automatic if you kept Watchtower: it 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.

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.

Prefer explicit updates — or need to roll back? Remove the watchtower: block and pin a specific version instead of latest:

    image: rangepulse/rangepulse:1.3.111

Then docker compose pull && docker compose up -d. To roll back after a problematic update, pin the previous version tag the same way and run those two commands again. Note: only tags 1.3.110 and newer exist on Docker Hub (see the advisory above) — older tags were deliberately removed and cannot be pulled.

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:

curl -s http://localhost/health

This prints something like {"status": "ok", "version": "1.3.111"}. (If you changed the port, use http://localhost:8080/health.)

Check the web-server 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 2 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_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.

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.

Before you start: you need a domain name pointed at your server's public IP, and ports 80 and 443 reachable from the internet (router port-forwarding if you're at home).

Step 1: In your ~/rangepulse folder, create a file named Caddyfile (no extension) containing:

health.yourdomain.com {
    reverse_proxy rangepulse:8000
}

Note the target is rangepulse:8000 — the service name from the compose file — not localhost. Inside the Caddy container, "localhost" means Caddy itself.

Step 2: Replace your docker-compose.yml with this version. Two things change: the rangepulse service no longer publishes a port (Caddy reaches it over Docker's internal network, and freeing port 80 lets Caddy have it), and a caddy service plus its two volumes are added:

services:
  rangepulse:
    image: rangepulse/rangepulse:latest
    volumes:
      - rangepulse_data:/data
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    env_file:
      - .env

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

  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:
  caddy_data:
  caddy_config:

Step 3: Apply it: cd ~/rangepulse && docker compose up -d. Caddy will automatically get a Let's Encrypt certificate, and RangePulse is available at https://health.yourdomain.com.

Other options:

• Nginx + certbot — if nginx runs on the host it needs port 80 itself, so first remap RangePulse in docker-compose.yml to "8080:8000" and apply with docker compose up -d. Then use proxy_pass http://localhost:8080; in your server block and 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 multiple 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 an old laptop or home server 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 account's address to the ADMIN_EMAILS setting in the .env file you created in Step 3.

As of v1.3.112, ADMIN_EMAILS matching is case-insensitive — any casing works. On shared or internet-exposed installations, any case-variant of a listed admin username is treated as the same admin account — keep registration closed to people you trust.

echo 'ADMIN_EMAILS=yourusername@localhost' >> ~/rangepulse/.env

Then apply it:

cd ~/rangepulse && 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 email, so the "Forgot Password" link can't email you a reset link. If you're locked out, use the built-in management tool:

docker exec -it <your-container-name> python3 manage.py reset-password

(Find your container name with docker ps — with our example compose file it's rangepulse-rangepulse-1. On images older than v1.3.108, add -e RANGEPULSE_DB=/data/rangepulse.db right after -it.)

The tool is interactive: it shows your account(s), asks you to pick one if there's more than one, and prompts for a new password (minimum 8 characters). Nothing appears on screen while you type the password — that's normal.

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. Weight is stored as a whole number — decimal places are not kept.
• 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 a new reading crosses one of your goals — it goes from missing the goal to meeting it, for example your blood pressure drops to or below your target — a brief notification appears at the top of the screen confirming the achievement. It dismisses automatically after a few seconds. Each goal celebrates at most once every 30 days, so you won't get a popup every single day you stay on target.

Time Range Selection

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

Free Cloud plan: charts show the last 30 days regardless of the range you pick. Your older readings are still stored — they're always included when you export, and upgrading makes them visible again.

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, flagged readings, trend arrows, and reading counts — designed to give your doctor the information they need at a glance.

Availability: included with the paid Cloud plans (Solo and Family) and with every self-hosted install. Not included in the Free Cloud plan. Generating the report is desktop-only — open RangePulse on a computer.

How to Generate a Report

1. From the dashboard (on a computer), 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 — blood pressure is categorized according to the AHA/ACC 2017 guidelines (Normal, Elevated, Stage 1, Stage 2, Crisis — see Trends and Insights).
• Flagged readings — a table calling out readings that deserve attention: blood pressure at or above 180/120 (flagged CRISIS), at or above 160/100 (HIGH), below 90/60 (LOW), and heart rate above 120 or below 50 bpm.
• 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

Import and export are desktop-only — open RangePulse on a computer to use them.

Importing Data

You can import historical readings from a CSV file. These are the columns RangePulse recognizes:

date,weight,heart_rate,blood_pressure,mileage,notes

Only the date column is required. Include whichever other columns you have; leave any cell blank if you don't have data for that metric on a given day. 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, MM/DD/YYYY, or MM/DD/YY all work.
• weight — numeric value in your preferred unit (stored as a whole number).
• heart_rate — beats per minute, whole number.
• blood_pressure — systolic/diastolic in one column (e.g., 128/82), not two separate columns.
• mileage — numeric distance.
• notes — free text (optional).

To import, go to the Data menu at the bottom of the dashboard and choose Import Data, then upload your CSV file.

How import handles problems: rows with an unreadable date or an out-of-range value are skipped, not fixed — and the rest of the file still imports. When it finishes you get a report like "Imported 340 rows, skipped 2 rows." Limits: up to 10,000 rows per file (split bigger files and import them one at a time), and gzip-compressed files (.csv.gz) are accepted up to 5 MB (upload size).

Exporting Data

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

• CSV — a spreadsheet-compatible file. The first column is an id RangePulse assigns to each entry, followed by the columns 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.

Export is never paywalled. On every plan — including the Free Cloud plan — export always includes your complete history, not just the last 30 days. Your data is yours.

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

The doctor visit report classifies blood pressure 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

Flagged readings appear in the doctor visit report (PDF), not on the dashboard. The report includes a table of readings that deserve attention: blood pressure at or above 180/120 (flagged CRISIS), at or above 160/100 (HIGH), or below 90/60 (LOW), plus heart rate above 120 or below 50 bpm.

A flag is a visual indicator that helps you and your doctor spot notable readings. It is not an emergency alert. RangePulse never watches your readings in real time and will never contact emergency services for you — if a reading is very high (higher than 180/120) and you have symptoms like chest pain, shortness of breath, or vision changes, call 911 or your local emergency number right away.

7. Account Management

Changing Your Password

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

Forgot Your Password? (Cloud)

On the login page, click "Forgot your password?" and enter your account email. We'll send you a reset link — it expires in 1 hour, so use it soon. Click the link, choose a new password, and log in.

No email after a few minutes? Check your spam folder, and make sure you entered the exact email you signed up with — for privacy reasons the form responds the same way whether or not an account exists, so a typo won't produce an error message.

Self-hosted? Your install can't send email — use the built-in reset tool instead: see Password Reset (Self-Hosted).

Two-Factor Authentication (2FA)

2FA adds a second check at login: your password plus a 6-digit code from an authenticator app (Google Authenticator, Authy, 1Password, and similar all work).

To turn it on:

1. Go to your Account page and find Two-factor authentication, then click Set up 2FA.
2. Scan the QR code with your authenticator app.
3. Enter the 6-digit code your app shows to confirm.
4. Save your recovery codes. They're shown once — use the Copy all or Download as .txt buttons and store them somewhere safe (a password manager is ideal). Each recovery code can be used once in place of an authenticator code.

Logging in with 2FA: enter your password as usual, then the 6-digit code from your app. If you don't have your device, enter one of your recovery codes instead. You can regenerate a fresh set of recovery codes any time from the Security page (this invalidates the old set).

Lost your device?

• Cloud: on the 2FA prompt, click "I can't use my authenticator" and enter your email. We send a reset link; for security there is a mandatory 24-hour waiting period after you first use it. After 24 hours, click the link in the email a second time — that second click disables 2FA so you can log in with your password alone (and set 2FA up again).
• Self-hosted: the email reset isn't available (self-host sends no email) — use one of your recovery codes. If you've lost both your device and your recovery codes, email hello@rangepulse.com for guidance.

To turn it off: Account → Two-factor authentication → Manage, then confirm with your password. Note that resetting your password never bypasses 2FA — you always need your app or a recovery code to finish logging in.

Exporting Your Data

You can download all of your data at any time — on every plan, always your complete history. Open the Data menu at the bottom of the dashboard (on a computer — export is desktop-only) 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 right away. Deleted entries go to a Recycle Bin:

• 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 — you have 35 days from deletion to do this. (Restoring a single entry is desktop-only; on mobile use Restore All.)
• After 35 days, entries can no longer be restored. They are permanently erased from our systems 90 days after deletion.

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.

Cancelling Your Cloud Subscription

Cancelling stops billing. It never deletes anything. Your account and every reading stay exactly as they are — you just move to the Free plan, and you can log in any time.

The easiest way: log in, go to Account → Billing, click Manage subscription, and choose Cancel subscription.

Can't log in? Use app.rangepulse.com/cancel — no login needed. Enter your email address and your Customer ID (e.g. RP-1234, shown on your Account page) and submit. All of your active subscriptions are cancelled immediately, and you'll get a confirmation email — which says it in so many words: nothing is deleted.

Family plans: cancelling a Family plan also moves your family members to the Free plan.

Refunds — 30-Day Money-Back Guarantee

Every paid plan comes with a 30-day money-back guarantee, and you don't need to email anyone: on your Account page, click Get an instant refund. One click refunds your latest payment instantly, cancels your plan, and keeps all your data — you move to the Free plan. This works for any payment made within the last 30 days (monthly or annual). After 30 days, cancelling stops future charges but the current period is not refundable.

Deleting Your Account

Cloud: go to your Account page, scroll to the bottom, enter your password, and click Delete My Account. Your account is then scheduled for deletion with a 7-day grace period:

• Changed your mind? Log back in any time during the 7 days and click Keep my account — the deletion is cancelled and nothing is lost.
• Want it gone now? After scheduling deletion, you can use the Delete Now option: re-enter your password and type DELETE to confirm, and your account and all data are permanently removed immediately.
• If you do nothing, your account and all data are permanently deleted when the 7 days are up.

Self-hosted: account deletion is immediate and permanent — there is no grace period.

8. Maintenance (Self-Hosted)

Backing Up Your Data

RangePulse stores all data in a Docker volume. With the standard ~/rangepulse setup, the volume's real name is rangepulse_rangepulse_data (Docker prefixes the folder name — run docker volume ls to confirm yours). To back up:

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

Now verify the backup — never skip this step:

tar -tzf rangepulse-backup.tar.gz | head

You should see files listed, including ./rangepulse.db. If the listing is empty, your backup is empty — the volume name was wrong (Docker silently creates a new empty volume for any name you mistype). Run docker volume ls, find the volume ending in _rangepulse_data, and redo the backup with that exact name.

Store the verified rangepulse-backup.tar.gz file somewhere safe — ideally on a different machine or drive.

Restoring from Backup

Use the same volume name you verified above:

cd ~/rangepulse
docker compose stop
docker run --rm -v rangepulse_rangepulse_data:/data -v "$(pwd)":/backup alpine \
  sh -c "rm -rf /data/* /data/.[!.]* ; tar xzf /backup/rangepulse-backup.tar.gz -C /data"
docker compose start

Then open RangePulse in your browser and confirm your readings are back before you trust the restore.

Viewing Logs

docker compose logs -f rangepulse

Press Ctrl+C to stop following the log output. This shows the web server's access and error output — usually all you need for troubleshooting, and it's what to include when emailing support.

The app also writes a more detailed log file, but by default it lives inside the container and is lost every time the container updates. If you want a detailed log that survives updates, add this line to your .env and run docker compose up -d:

RANGEPULSE_LOG_FILE=/data/rangepulse.log

The log then lives on your data volume alongside the database.

Checking Disk Usage

docker system df

Automatic Updates

The default docker-compose.yml includes Watchtower. It 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 and access — the honest version: Watchtower only contacts Docker Hub, and it sends no user data, no health data, and no telemetry. But to do its job it mounts the Docker control socket (/var/run/docker.sock), which is full administrative control of Docker on your machine — it could manage any container, not just RangePulse. That's how every Docker auto-updater works, but you should know it. Our template limits which containers it updates to those with the enable label (just RangePulse), and if you'd rather not run it at all, delete the watchtower: block and update manually:

docker compose pull && docker compose up -d

Reminder: never run two Watchtowers on one machine — a newly started Watchtower stops the existing one (see the warning in the installation section).

9. Troubleshooting

Container will not start

Check the logs for error messages:

docker compose logs rangepulse

Common causes:

• Missing .env file. Compose refuses to start without it: cd ~/rangepulse && touch .env
• Port 80 already in use. Change the first number of the port mapping in docker-compose.yml (e.g., "8080:8000"). The second number must stay 8000 — that's the app's port inside the container.
• 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 which host port is mapped to the app: docker compose port rangepulse 8000
• If running on a remote server, connect to the server's IP address instead of localhost.

Data not appearing after import

• Make sure your CSV has a header row and at least a date column — that's the only required one.
• Dates can be YYYY-MM-DD, MM/DD/YYYY, or MM/DD/YY.
• Blood pressure must be in systolic/diastolic format in one column (e.g., 128/82), not two separate columns.
• Check the result message — it tells you how many rows imported and how many were skipped. Skipped rows usually have an unreadable date or an out-of-range value.

PDF report not generating

• On the Free Cloud plan? Doctor PDF reports require a paid plan — upgrading on your Account page unlocks them.
• On a phone? The doctor report is desktop-only — open RangePulse on a computer.
• 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 — Cloud or self-hosted — email us:

• Email: hello@rangepulse.com

When emailing about a technical issue, please include:

• Which version you are using (Cloud or self-hosted — for self-hosted, the version number from curl -s http://localhost/health or your Account page)
• Your browser and device (e.g., Chrome on iPhone, Firefox on Windows)
• What happened and what you expected to happen
• A screenshot if possible — and for self-hosted issues, the last lines of docker compose logs rangepulse