A web-based configuration tool for Homepage dashboard. This tool provides a visual interface to create and manage Homepage service configurations without manually editing YAML files.

• 🔐 Authentication - Secure login with configurable username and password
• 🎨 Visual Configuration Editor - Add, edit, and delete services through a user-friendly interface
• 🔄 Drag & Drop - Reorder services and categories with drag-and-drop functionality
• 👁️ Live Homepage Preview - Display your actual Homepage dashboard in an iframe for real-time preview
• 📥 Import/Export - Import existing YAML configurations and export your changes
• 🔖 Bookmarks Management - Manage Homepage bookmarks with dedicated UI
• 🔧 Widget Support - Full support for all Homepage widget types including:
  • Media widgets (Emby, Jellyfin, Plex, etc.)
  • Download clients (qBittorrent, Transmission)
  • Custom API widgets
  • Home Assistant, Synology, and more
• 🐳 Docker Support - Easy deployment with Docker and docker-compose
• 🚀 CI/CD - Automated builds with GitHub Actions

# Clone the repository
git clone https://github.com/thsrite/homepage-config.git
cd homepage-config

# Start with docker-compose
docker-compose up -d

# Access the tool
# Open http://localhost:9835 in your browser

docker run -d \
  --name homepage-config \
  -p 9835:9835 \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=your-secure-password \
  -v ./homepage/services.yaml:/app/config/services.yaml \
  -v ./homepage/bookmarks.yaml:/app/config/bookmarks.yaml \
  -v /path/to/your/icons:/app/public/images \
  --restart unless-stopped \
  thsrite/homepage-config:latest

Note: The -v /path/to/your/icons:/app/public/images mount is optional but required if you want to use local icon files with /images/ paths.

⚠️ Important: You MUST set AUTH_USERNAME and AUTH_PASSWORD environment variables!

docker run -d \
  --name homepage-config \
  -p 9835:9835 \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=your-secure-password \
  -v ./homepage/services.yaml:/app/config/services.yaml \
  -v ./homepage/bookmarks.yaml:/app/config/bookmarks.yaml \
  -v /path/to/your/icons:/app/public/images \
  thsrite/homepage-config:latest

• Python 3.8 or higher
• pip (Python package manager)

1. Clone the repository:

git clone https://github.com/thsrite/homepage-config.git
cd homepage-config

2. Install Python dependencies:

pip install -r requirements.txt

3. Run the application:

python3 run.py

4. Create a .env file with required authentication settings:

cp .env.example .env
# Edit .env and set your username and password

5. Run the application:

python3 run.py

6. Open your browser and navigate to:

http://localhost:9835

Authentication is required for all deployments. You must configure a username and password via environment variables.

Edit your docker-compose.yml to set authentication credentials:

services:
  homepage-config:
    image: thsrite/homepage-config:latest
    environment:
      - AUTH_USERNAME=your-username  # Change this!
      - AUTH_PASSWORD=your-password  # Change this!
      - SESSION_SECRET=your-random-secret-key
    ports:
      - "9835:9835"
    volumes:
      - ./homepage/services.yaml:/app/config/services.yaml
      - ./homepage/bookmarks.yaml:/app/config/bookmarks.yaml
      - /path/to/your/icons:/app/public/images  # Optional: for local icons

For local development, create a .env file:

AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password
SESSION_SECRET=your-random-secret-key

1. Click the "Add Category" button in the Configuration Editor
2. Enter a name for your category (e.g., "Media", "Tools", "Downloads")
3. The category will appear in the editor

1. Click "Add Service" within a category

2. Fill in the service details:

   • Service Name - Display name for the service
   • Icon URL - Icon for the service, supports:
     • External URLs: https://example.com/icon.png
     • Local images: /images/myicon.png (requires volume mount, see below)
   • Service URL - Link to access the service
   • Health Check URL - URL to check if service is online
   • Server/Container - Docker server and container names (optional)

3. Configure widget (optional):

   • Select widget type from dropdown
   • Fill in widget-specific configuration
   • For Custom API widgets, add field mappings

4. Click "Save Service"

• Drag services using the grip handle (⋮) to reorder within a category
• Drag services between categories to move them
• Drag categories to reorder them

1. Click "Import" in the top navigation
2. Select your existing services.yaml file
3. Click "Import" to load the configuration

1. Click "Export" in the top navigation
2. The services.yaml file will be downloaded
3. Copy it to your Homepage configuration directory

The right panel can display your actual Homepage dashboard:

1. Enter your Homepage URL in the input field (e.g., http://localhost:3000)
2. Click "Set URL" to load your Homepage in the preview panel
3. Click "Refresh" to reload the Homepage after making configuration changes
4. The URL is saved in your browser for future sessions

# Build locally
docker build -t homepage-config:latest .

# Build for multiple platforms
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t homepage-config:latest .

version: '3.8'

services:
  homepage-config:
    image: thsrite/homepage-config:latest
    container_name: homepage-config
    restart: unless-stopped
    ports:
      - "9835:9835"
    volumes:
      - ./homepage/services.yaml:/app/config/services.yaml
      - ./homepage/bookmarks.yaml:/app/config/bookmarks.yaml
      - /volume1/docker/homepage/image:/app/public/images  # Optional: for local icons
    environment:
      - PORT=9835
      - DEBUG=false

Using Local Icons: To use local icon files instead of external URLs:

1. Mount a directory to /app/public/images in the container
2. Place your icon files in the mounted directory on the host
3. Reference icons in the service configuration as /images/filename.png
4. Example: If you have /volume1/docker/homepage/image/myapp.png on the host, use /images/myapp.png in the Icon URL field

• Generated config: config/services.yaml
• Backups: config/backups/
• Uploads: uploads/

widget:
  type: emby
  url: http://10.0.0.2:8096
  key: your_api_key_here
  enableBlocks: true
  enableNowPlaying: true

widget:
  type: qbittorrent
  url: http://10.0.0.2:8889
  username: admin
  password: your_password

widget:
  type: customapi
  url: http://10.0.0.2:3003/api/v1/stats
  method: GET
  mappings:
    - field: downloads
      label: Downloads
    - field: uploads
      label: Uploads

The application provides a REST API for programmatic access:

• GET /api/services/ - Get all services
• POST /api/services/ - Create a new service
• PUT /api/services/{category}/{name} - Update a service
• DELETE /api/services/{category}/{name} - Delete a service
• GET /api/categories/ - Get all categories
• POST /api/categories/ - Create a new category
• GET /api/config/export - Export configuration as YAML
• POST /api/config/import - Import YAML configuration

Full API documentation is available at: http://localhost:9835/docs

homepage-config/
├── backend/           # FastAPI backend
│   ├── api/          # API endpoints
│   ├── core/         # Core functionality
│   └── models/       # Data models
├── frontend/         # HTML/JS frontend
│   ├── static/       # CSS, JS, images
│   └── index.html    # Main page
├── config/          # Configuration files
├── .github/          # GitHub Actions workflows
├── requirements.txt  # Python dependencies
├── Dockerfile        # Docker image definition
├── docker-compose.yml # Docker compose configuration
├── run.py           # Development server
└── README.md        # This file

• Backend: FastAPI, Python 3.8+
• Frontend: HTML5, Bootstrap 5, JavaScript
• Libraries: SortableJS (drag-drop), Axios (HTTP client)
• Deployment: Docker, GitHub Actions

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

If port 9835 is already in use, you can change it:

Docker:

docker run -p 8081:9835 ...

Local:

# In run.py
uvicorn.run(
    "main:app",
    host="0.0.0.0",
    port=8081,  # Change to desired port
    ...
)

• Check for tab characters in YAML (will be auto-fixed)
• Ensure YAML syntax is valid
• Remove inline comments if causing issues

• Check if Homepage is running
• Verify the URL is correct
• Try using IP address instead of hostname
• Check for CORS/iframe restrictions

1. Export the configuration
2. Copy services.yaml to Homepage config directory
3. Restart Homepage container/service
4. Click Refresh in the preview panel

This project is licensed under the MIT License - see the LICENSE file for details.

• Homepage - The awesome dashboard this tool configures
• FastAPI - Modern web framework for building APIs
• Bootstrap - CSS framework for responsive design
• SortableJS - Drag and drop library

For issues, questions, or suggestions:

1. Check the troubleshooting section
2. Review Homepage documentation
3. Open an issue on GitHub

• Multi-language support
• Dark mode theme
• Configuration templates library
• Service status checking
• Bulk import/export
• Configuration validation warnings
• Keyboard shortcuts
• Mobile responsive design improvements

Made with ❤️ for the Homepage community