Deploying Hiccup

Introduction

Hiccup is a beautiful, customizable static start page designed to be your browser’s home. With drag-and-drop widgets, built-in search, and PWA support, Hiccup provides a fast, distraction-free way to access your most important links and daily productivity tools.

Built as a lightweight static application, Hiccup stores all configuration in LocalStorage, meaning your data never leaves your browser. The application features a clean, modern interface with customizable widgets for tasks, notes, bookmarks, weather, calendar integration, and more.

Key highlights of Hiccup:

• Static Start Page: Fast, lightweight homepage for your browser
• Drag-and-Drop Widgets: Customize layout with movable widgets
• Built-in Search: Quick search with customizable providers
• PWA Support: Install as a progressive web app
• LocalStorage: All data stays in your browser
• No Backend Required: Pure frontend application
• Integrations: GitHub, Trello, OpenWeatherMap, and more
• Keyboard Shortcuts: Navigate quickly with keyboard

This guide walks through deploying Hiccup on Klutch.sh using Docker, configuring your start page, and customizing widgets.

Prerequisites

Before deploying Hiccup on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Hiccup configuration
• (Optional) API keys for weather and calendar integrations
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

hiccup-deploy/
├── Dockerfile
├── config.json (optional)
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the Hiccup image:

FROM bleckbeard/hiccup:latest

# Expose the web server port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1

Dockerfile with Custom Configuration

To include a custom configuration:

FROM bleckbeard/hiccup:latest

# Copy custom configuration
COPY config.json /usr/share/nginx/html/configs/config.json

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1

Sample Configuration File

Create a config.json for default settings:

{
  "theme": "dark",
  "search": {
    "engine": "google",
    "placeholder": "Search..."
  },
  "bookmarks": [
    {
      "name": "GitHub",
      "url": "https://github.com",
      "icon": "github"
    },
    {
      "name": "Gmail",
      "url": "https://mail.google.com",
      "icon": "mail"
    }
  ],
  "weather": {
    "enabled": true,
    "location": "New York",
    "units": "metric"
  }
}

Deploying Hiccup on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile config.json .dockerignore README.md
git commit -m "Initial Hiccup deployment configuration"
git remote add origin https://github.com/yourusername/hiccup-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “hiccup” or “startpage”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Hiccup repository.

Configure HTTP Traffic

• Select HTTP as the traffic type
• Set the internal port to 80

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container and start Hiccup with HTTPS enabled.

Access Hiccup

Once deployment completes, access your start page at https://your-app-name.klutch.sh.

Set as Browser Homepage

Configure your browser to use your Hiccup URL as the homepage:

• Chrome: Settings > On startup > Open a specific page
• Firefox: Preferences > Home > Custom URLs
• Edge: Settings > Start, home, and new tabs

Customizing Hiccup

Adding Bookmarks

1. Click the edit icon on the bookmarks widget
2. Add new bookmarks with name, URL, and icon
3. Drag to reorder bookmarks
4. Save changes

Weather Widget

1. Enable the weather widget
2. Enter your location
3. Optionally configure OpenWeatherMap API key
4. Choose temperature units

Search Configuration

Configure search engines:

1. Click settings icon
2. Select default search engine
3. Available options:
   • Google
   • DuckDuckGo
   • Bing
   • Custom search URLs

Theme Customization

1. Access settings
2. Choose light or dark theme
3. Customize accent colors
4. Adjust widget opacity

Available Widgets

Productivity:

• Bookmarks with icons
• Quick notes
• To-do lists
• Calendar events

Information:

• Weather forecast
• Clock and date
• Search bar
• RSS feeds (via integrations)

Integrations:

• GitHub activity
• Trello boards
• OpenWeatherMap

Keyboard Shortcuts

Navigate quickly with keyboard:

Key	Action
/	Focus search
Esc	Clear search
1-9	Open bookmark by number
e	Edit mode
?	Show help

Privacy Features

Hiccup respects your privacy:

• LocalStorage Only: Data never sent to servers
• No Analytics: No tracking or telemetry
• No Accounts: No registration required
• Export/Import: Backup settings as JSON

Troubleshooting

Configuration Not Loading

• Check JSON syntax in config.json
• Clear browser LocalStorage
• Verify file path in Dockerfile

Weather Not Showing

• Verify location is correct
• Check API key if using OpenWeatherMap
• Ensure internet connectivity

Widgets Not Saving

• Check browser allows LocalStorage
• Verify not in private/incognito mode
• Clear browser cache and retry

Additional Resources

• Hiccup GitHub Repository
• Hiccup Docker Hub
• OpenWeatherMap API
• Klutch.sh Deployments

Conclusion

Deploying Hiccup on Klutch.sh provides a beautiful, customizable start page accessible from any device. The privacy-focused design keeps your data local while the widget system enables powerful productivity features. Whether you need a simple bookmark launcher or a full-featured dashboard, Hiccup delivers a fast, distraction-free experience for your browser homepage.