feat: add Docker support with environment configuration and health checks

2025-07-02 19:10:32 +00:00
parent 4fe02675ec
commit d7f4894c7c
7 changed files with 350 additions and 1 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -0,0 +1,25 @@
+node_modules
+.next
+.git
+.gitignore
+README.md
+.env.local
+.env.example
+*.log
+.DS_Store
+Thumbs.db
+.vscode
+.idea
+coverage
+.nyc_output
+*.tgz
+*.tar.gz
+.cache
+.parcel-cache
+dist
+build
+.vercel
+.netlify
+.turbo
+.github
+4xnored.png
--- a/.env.docker
+++ b/.env.docker
@@ -0,0 +1,21 @@
+# Docker Environment Configuration
+# Copy this file to .env and modify the values as needed
+
+# Host configuration
+HOST_PORT=3000
+PORT=3000
+
+# Navidrome Server Configuration (OPTIONAL)
+# If not provided, the app will prompt you to configure these settings
+# NAVIDROME_URL=http://localhost:4533
+# NAVIDROME_USERNAME=your_username
+# NAVIDROME_PASSWORD=your_password
+
+# PostHog Analytics (optional)
+POSTHOG_KEY=
+POSTHOG_HOST=
+
+# Example for external Navidrome server:
+# NAVIDROME_URL=https://your-navidrome-server.com
+# NAVIDROME_USERNAME=your_username
+# NAVIDROME_PASSWORD=your_password
--- a/DOCKER.md
+++ b/DOCKER.md
@@ -0,0 +1,171 @@
+# Docker Deployment
+
+This application can be easily deployed using Docker with configurable environment variables.
+
+## Quick Start
+
+### Using Docker Run
+
+```bash
+# Run using pre-built image (app will prompt for Navidrome config)
+docker run -p 3000:3000 ghcr.io/sillyangel/mice:latest
+
+# Or build locally
+docker build -t mice .
+docker run -p 3000:3000 mice
+
+# Run with pre-configured Navidrome settings
+docker run -p 3000:3000 \
+  -e NEXT_PUBLIC_NAVIDROME_URL=http://your-navidrome-server:4533 \
+  -e NEXT_PUBLIC_NAVIDROME_USERNAME=your_username \
+  -e NEXT_PUBLIC_NAVIDROME_PASSWORD=your_password \
+  -e PORT=3000 \
+  ghcr.io/sillyangel/mice:latest
+```
+
+### Using Docker Compose
+
+1. Copy the environment template:
+
+   ```bash
+   cp .env.docker .env
+   ```
+
+2. Edit `.env` with your configuration:
+
+   ```bash
+   nano .env
+   ```
+
+3. Start the application:
+
+   ```bash
+   docker-compose up -d
+   ```
+
+**Note**: The default docker-compose.yml uses the pre-built image `ghcr.io/sillyangel/mice:latest`.
+
+For local development, you can use the override example:
+
+```bash
+cp docker-compose.override.yml.example docker-compose.override.yml
+# This will build locally instead of using the pre-built image
+```
+
+## Configuration Options
+
+All configuration is done through environment variables. If Navidrome server configuration is not provided via environment variables, the application will automatically prompt you to configure it within the client interface.
+
+### Optional Variables
+
+- `NEXT_PUBLIC_NAVIDROME_URL`: URL of your Navidrome server (optional - app will prompt if not set)
+- `NEXT_PUBLIC_NAVIDROME_USERNAME`: Navidrome username (optional - app will prompt if not set)
+- `NEXT_PUBLIC_NAVIDROME_PASSWORD`: Navidrome password (optional - app will prompt if not set)
+- `PORT`: Port for the application to listen on (default: `3000`)
+- `HOST_PORT`: Host port to map to container port (docker-compose only, default: `3000`)
+- `NEXT_PUBLIC_POSTHOG_KEY`: PostHog analytics key (optional)
+- `NEXT_PUBLIC_POSTHOG_HOST`: PostHog analytics host (optional)
+
+## Examples
+
+### Basic Setup (App will prompt for configuration)
+
+```bash
+# Using pre-built image - app will ask for Navidrome server details on first launch
+docker run -p 3000:3000 ghcr.io/sillyangel/mice:latest
+
+# Or build locally
+docker build -t mice .
+docker run -p 3000:3000 mice
+```
+
+### Pre-configured Development Setup
+
+```bash
+docker run -p 3000:3000 \
+  -e NEXT_PUBLIC_NAVIDROME_URL=http://localhost:4533 \
+  -e NEXT_PUBLIC_NAVIDROME_USERNAME=admin \
+  -e NEXT_PUBLIC_NAVIDROME_PASSWORD=admin \
+  ghcr.io/sillyangel/mice:latest
+```
+
+### Pre-configured Production Setup
+
+```bash
+docker run -p 80:3000 \
+  -e NEXT_PUBLIC_NAVIDROME_URL=https://music.yourdomain.com \
+  -e NEXT_PUBLIC_NAVIDROME_USERNAME=your_user \
+  -e NEXT_PUBLIC_NAVIDROME_PASSWORD=your_secure_password \
+  -e PORT=3000 \
+  --restart unless-stopped \
+  ghcr.io/sillyangel/mice:latest
+```
+
+### Using Environment File
+
+#### Option 1: Let the app prompt for configuration
+
+Create a minimal `.env` file:
+
+```env
+PORT=3000
+HOST_PORT=80
+```
+
+#### Option 2: Pre-configure Navidrome settings
+
+Create a `.env` file with Navidrome configuration:
+
+```env
+NAVIDROME_URL=https://music.yourdomain.com
+NAVIDROME_USERNAME=your_user
+NAVIDROME_PASSWORD=your_secure_password
+PORT=3000
+HOST_PORT=80
+```
+
+Then run either way:
+
+```bash
+docker-compose up -d
+```
+
+## Health Check
+
+The Docker Compose setup includes a health check that verifies the application is responding correctly. You can check the health status with:
+
+```bash
+docker-compose ps
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection refused**: Ensure your Navidrome server is accessible from the Docker container
+2. **Authentication failed**: Verify your username and password are correct
+3. **Port conflicts**: Change the `HOST_PORT` if port 3000 is already in use
+
+### Logs
+
+View application logs:
+
+```bash
+# Docker run
+docker logs <container_name>
+
+# Docker compose
+docker-compose logs -f mice
+```
+
+### Container Shell Access
+
+Access the container for debugging:
+
+```bash
+# Docker run
+docker exec -it <container_name> sh
+
+# Docker compose
+docker-compose exec mice sh
+```
--- a/38
+++ b/38
@@ -0,0 +1,38 @@
+# Use Node.js 22 Alpine for smaller image size
+FROM node:22-alpine
+
+# Install pnpm globally
+RUN npm install -g pnpm@9.15.3
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package.json pnpm-lock.yaml ./
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Set default environment variables (can be overridden at runtime)
+# Navidrome configuration is optional - app will prompt if not provided
+ENV NEXT_PUBLIC_NAVIDROME_URL=""
+ENV NEXT_PUBLIC_NAVIDROME_USERNAME=""
+ENV NEXT_PUBLIC_NAVIDROME_PASSWORD=""
+ENV NEXT_PUBLIC_POSTHOG_KEY=""
+ENV NEXT_PUBLIC_POSTHOG_HOST=""
+ENV PORT=3000
+
+# Generate git commit hash for build info (fallback if not available)
+RUN echo "NEXT_PUBLIC_COMMIT_SHA=docker-build" > .env.local
+
+# Build the application
+RUN pnpm build
+
+# Expose the port
+EXPOSE $PORT
+
+# Start the application
+CMD ["sh", "-c", "pnpm start -p $PORT"]
--- a/README.md
+++ b/README.md
@@ -44,12 +44,14 @@ pnpm install
 cp .env.example .env
 ```

-Edit `.env.local` with your Navidrome server details:
+Edit `.env` with your Navidrome server details:

 ```env
 NEXT_PUBLIC_NAVIDROME_URL=http://localhost:4533
 NEXT_PUBLIC_NAVIDROME_USERNAME=your_username
 NEXT_PUBLIC_NAVIDROME_PASSWORD=your_password
+NEXT_PUBLIC_POSTHOG_KEY=phc_XXXXXXXXXXXXXXXXXX
+NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
 ```

 3. **Run the development server**
@@ -60,6 +62,42 @@ pnpm dev

 Open [http://localhost:40625](http://localhost:40625) in your browser.

+## Docker Deployment
+
+For easy deployment using Docker:
+
+### Quick Docker Setup
+
+```bash
+# Run using pre-built image (app will prompt for Navidrome configuration)
+docker run -p 3000:3000 ghcr.io/sillyangel/mice:latest
+
+# Or build locally
+docker build -t mice .
+docker run -p 3000:3000 mice
+```
+
+### Docker Compose (Recommended)
+
+```bash
+# Copy environment template and configure
+cp .env.docker .env
+# Edit .env with your settings (optional - app can prompt)
+docker-compose up -d
+```
+
+### Pre-configured Docker Run
+
+```bash
+docker run -p 3000:3000 \
+  -e NEXT_PUBLIC_NAVIDROME_URL=http://your-navidrome-server:4533 \
+  -e NEXT_PUBLIC_NAVIDROME_USERNAME=your_username \
+  -e NEXT_PUBLIC_NAVIDROME_PASSWORD=your_password \
+  ghcr.io/sillyangel/mice:latest
+```
+
+📖 **For detailed Docker configuration, environment variables, troubleshooting, and advanced setups, see [DOCKER.md](./DOCKER.md)**
+
 ## Migration from Firebase

 This project was migrated from Firebase to Navidrome. See [NAVIDROME_MIGRATION.md](./NAVIDROME_MIGRATION.md) for detailed migration notes and troubleshooting.
--- a/docker-compose.override.yml.example
+++ b/docker-compose.override.yml.example
@@ -0,0 +1,25 @@
+# Docker Compose Override Example for Local Development
+# This file shows how to override the default docker-compose.yml for local development
+
+version: '3.8'
+
+services:
+  mice:
+    # Override to build locally instead of using pre-built image
+    build: .
+    image: mice:local
+    
+    # Enable Navidrome configuration for development
+    environment:
+      - NEXT_PUBLIC_NAVIDROME_URL=http://localhost:4533
+      - NEXT_PUBLIC_NAVIDROME_USERNAME=admin
+      - NEXT_PUBLIC_NAVIDROME_PASSWORD=admin
+      - NEXT_PUBLIC_POSTHOG_KEY=${POSTHOG_KEY:-}
+      - NEXT_PUBLIC_POSTHOG_HOST=${POSTHOG_HOST:-}
+      - PORT=${PORT:-3000}
+    
+    # Mount source code for development (optional)
+    # volumes:
+    #   - .:/app
+    #   - /app/node_modules
+    #   - /app/.next
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -0,0 +1,31 @@
+version: '3.8'
+
+services:
+  mice:
+    image: ghcr.io/sillyangel/mice:latest
+    ports:
+      - "${HOST_PORT:-3000}:${PORT:-3000}"
+    environment:
+      # Navidrome Server Configuration (OPTIONAL)
+      # Uncomment and configure these if you want to pre-configure the server connection
+      # If not set, the app will prompt you to configure these settings on first launch
+      # - NEXT_PUBLIC_NAVIDROME_URL=${NAVIDROME_URL:-}
+      # - NEXT_PUBLIC_NAVIDROME_USERNAME=${NAVIDROME_USERNAME:-}
+      # - NEXT_PUBLIC_NAVIDROME_PASSWORD=${NAVIDROME_PASSWORD:-}
+      
+      # PostHog Analytics (optional)
+      - NEXT_PUBLIC_POSTHOG_KEY=${POSTHOG_KEY:-}
+      - NEXT_PUBLIC_POSTHOG_HOST=${POSTHOG_HOST:-}
+      
+      # Application Port
+      - PORT=${PORT:-3000}
+    
+    # Optional: Add a health check
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:${PORT:-3000}"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    
+    restart: unless-stopped