📖 Installation Guide

This guide covers all methods of installing and deploying MyAstroBoard.

Prerequisites

Required

• Docker
• Docker Compose
• Internet connection (for downloading images and target catalogues)

Running Home Assistant OS? You can skip Docker entirely and install MyAstroBoard as a Home Assistant app - see Option 2.

System requirements

Where the memory figure comes from: on a fresh install of the 1.8.2 image (two gunicorn workers), memory grows to about 720 MB once the first SkyTonight calculation has run, and stays there. Under a 512 MB limit without swap, a worker was killed for lack of memory during that calculation. The browser then sees failed requests: an action reports an error although it went through on the server, or the offline page appears. The 2 GB and 2-core recommendations are margins, not measurements.

The CPU mostly sets how long the calculations take. Requests stay fast on small CPUs (a quarter of a core still created an account in under half a second), but the first SkyTonight run after startup takes longer.

Keep the data directory on a local disk. SQLite cannot use its WAL mode on some network shares (NFS, SMB), which makes writes slow; the application log says so at startup.

At startup each worker writes a Host: line to the application log with the CPUs, memory (and the container limits, if any), swap and the file system of the data directory, and a warning when the memory is below 1 GB. Include it when you report an issue. The same memory warning is shown to administrators in App settings -> Metrics.

Installation

Option 1: Using Published Docker Image (Recommended for Users)

1. Create and move in the directory you want install this image

# Example
mkdir /opt/myastroboard
cd /opt/myastroboard

2. Download the docker-compose file:

curl -o docker-compose.yml https://raw.githubusercontent.com/myastroboard/myastroboard/main/docker-compose.yml

3. Start the application:

docker compose up -d

4. Access the dashboard: Open your browser and navigate to http://localhost:5000 or IP of your machine.

The system will automatically:

• Start the web dashboard
• Initialize the scheduler
• Run SkyTonight and cache schedulers automatically

5. Update to latest version - Not necessary at first install:

docker compose pull
docker compose up -d

Option 2: Home Assistant App

For Home Assistant OS or Supervised installations (not Home Assistant Container or Core), on a 64-bit system: amd64 or aarch64 (Raspberry Pi 4/5, Home Assistant Green/Yellow, any x86 PC). No Docker knowledge needed.

1. Add the repository: click the button below, or in Home Assistant go to Settings -> Apps -> App store, open the menu (top right) -> Repositories and add https://github.com/myastroboard/home-assistant-apps.

   Add repository to Home Assistant

2. Install and start: pick MyAstroBoard in the store, click Install, then Start.

3. Open the dashboard: click Open web UI, or turn on Show in sidebar to get a MyAstroBoard entry in the Home Assistant sidebar. The direct address (port 5000 on your Home Assistant host) stays available for what the sidebar panel cannot do: installable app, push notifications, Astrodex stream.

Updates are offered in Home Assistant like any other app, and the app’s data is included in Home Assistant backups. See the app’s documentation for the details and current limitations. The Home Assistant MQTT integration and the Lovelace card are separate and optional - see HOME_ASSISTANT.md.

Option 3: Build from Source (For Developers)

1. Clone the repository:

git clone https://github.com/myastroboard/myastroboard.git
cd myastroboard

2. Edit docker-compose.yml file (if necessary):

nano docker-compose.yml

3. Build the application:

docker compose build

4. Start the application:

docker compose up -d

5. Access the dashboard: Open your browser and navigate to http://localhost:5000

The system will automatically:

• Start the web dashboard
• Initialize the scheduler
• Run SkyTonight and cache schedulers automatically

6. Debug & venv

# Create venv
python -m venv venv

# Activate venv
# Windows
.\venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

# Install dev tools
pip install -r requirements-dev.txt

# Debug Launch
docker compose -f docker-compose-dev.yml -f docker-compose.debug.yml up --build

7. Tests

# Execute tests with covering
pytest --cov=backend tests/

# Execute specific test
pytest tests/skytonight/test_skytonight_targets.py -v

Advanced configuration

Security, Notifications & Reverse Proxy

These settings are configured entirely through the admin UI - no manual docker-compose editing required:

All settings persist in the data/ volume and survive container rebuilds and updates.

Push Notifications - VAPID Contact Email

After first login, go to App settings -> Configuration -> Notifications and enter a real email address. This is sent to push services (Apple APNs, Google FCM) as a contact address - it is never shown to users.

Without this setting, the app falls back to admin@localhost, which Apple APNs rejects, silently dropping all iOS push notifications.

iOS - Push Notifications Requirement

Push notifications on iOS require the app to be installed as a PWA (Progressive Web App):

1. Open the app in Safari on your iPhone or iPad.
2. Tap the Share button (square with arrow).
3. Select “Add to Home Screen”.
4. Launch the app from the Home Screen icon.

Push notifications will not work when opening the app directly in a Safari browser tab - they only work from the installed Home Screen shortcut. This is an Apple platform restriction.

The Test button (My settings -> Notifications) sends a real push through the server; on iOS, background or lock the app right after tapping it to see the notification. See MOBILE.md.

Remember Me Feature

The login page includes a “Remember me” checkbox (only visible when the HTTPS-only session cookie is enabled via App settings -> Configuration -> Reverse proxy):

• When checked: Keeps users logged in for 30 days
• When unchecked: Session expires when browser closes
• Availability: Only shown when using HTTPS for security
• HTTP mode: Feature is hidden; sessions always expire when browser closes
• Logout always clears all cookies and sessions

Default Credentials

On first run, a default admin account is created:

• Username: admin
• Password: admin

🔒 IMPORTANT: Change the default password immediately after first login! The application will display a warning banner until you do.

Environment Variables

The docker-compose file requires only these variables:

# Timezone for container logs (UTC recommended; set your observation timezone in App settings -> Configuration)
- TZ=UTC

# Flask debug mode
- FLASK_DEBUG=0

# App data directory (keep default)
- DATA_DIR=/app/data

Security, reverse proxy, and push notification settings are managed in the admin UI (App settings -> Configuration) and stored in the database.

Data Persistence

All configuration and outputs are stored in Docker volumes:

• ./data/ - All persistent data (survives container rebuilds)
• ./data/myastroboard.db - SQLite database: accounts, configuration, settings, Astrodex, equipment, plans, observation log, wishlist (details)
• ./data/astrodex/images/ - Astrodex pictures
• ./data/observation_sessions/attachments/ - Observation log attachments
• ./data/backups/ - Archive of the 1.6 data files, written once by the 1.7 upgrade
• ./data/cache/ - Main cache files (persisted across restarts; only transient lock files are removed)
• ./data/skytonight/ - SkyTonight main folder
  • ./data/skytonight/calculations/ - SkyTonight calculation outputs
  • ./data/skytonight/catalogues/ - Generated SkyTonight catalogues
  • ./data/skytonight/logs/ - SkyTonight logs (persisted for diagnostics)
  • ./data/skytonight/outputs/ - Graph outputs
  • ./data/skytonight/runtime/ - Runtime files for scheduler (status is persisted; transient lock/trigger files are cleaned on startup)

Important: These directories persist across Docker container rebuilds, ensuring your settings and data are never lost.

Getting started

When everything is installed, you can configure the interface in the web UI - see Quick Start.

Last updated 2026-11-13