Skip to content
Klutch.sh Docs

Deploying Our Shopping List

Introduction

Our Shopping List is an open-source, self-hosted collaborative shopping list application that helps families and groups manage shared shopping lists. Built as a Progressive Web App (PWA), it works seamlessly on mobile devices while providing real-time synchronization across all connected users.

Unlike commercial shopping list apps that store your data on third-party servers, Our Shopping List gives you complete control over your shopping data. The application supports multiple lists, categories, real-time sync, and offline functionality, making it practical for everyday use at home and in stores.

Key highlights of Our Shopping List:

  • Real-Time Sync: Changes sync instantly across all connected devices
  • Multiple Lists: Create separate lists for different stores or purposes
  • Categories: Organize items by category for efficient shopping
  • Offline Support: Works without internet, syncs when connected
  • PWA: Install as an app on mobile devices
  • Share Lists: Invite family members to collaborate on lists
  • Simple Interface: Clean, easy-to-use design
  • No Account Required: Optional authentication for sharing
  • Self-Hosted Privacy: Your shopping data stays on your server
  • Lightweight: Minimal resource requirements

This guide walks through deploying Our Shopping List on Klutch.sh using Docker, setting up sharing, and configuring the application for family use.

Why Deploy Our Shopping List on Klutch.sh

Deploying Our Shopping List on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys your shopping list app. Push to GitHub, and your service deploys automatically.

Persistent Storage: Attach persistent volumes for database storage. Your shopping lists survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, required for PWA installation and secure access.

Always-On Availability: Your shopping list is available 24/7 for the whole family.

GitHub Integration: Store configuration in Git for version-controlled infrastructure.

Custom Domains: Use a memorable domain for easy access on mobile devices.

Data Privacy: Keep your shopping habits private on your own infrastructure.

Prerequisites

Before deploying Our Shopping List on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • Mobile devices for testing PWA installation

Understanding Our Shopping List Architecture

Our Shopping List has a simple architecture:

Node.js Backend: Handles API requests, real-time sync via WebSockets, and data persistence.

Vue.js Frontend: Progressive Web App providing the user interface, with offline capability via service workers.

SQLite/MongoDB Database: Stores lists, items, and user data.

WebSocket Server: Enables real-time synchronization between connected clients.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

shopping-list-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile for Our Shopping List:

FROM node:18-alpine


WORKDIR /app


# Install git for cloning
RUN apk add --no-cache git


# Clone the repository
RUN git clone https://github.com/nanawel/our-shopping-list.git .


# Install dependencies
RUN npm install


# Build the frontend
RUN npm run build


# Environment configuration
ENV NODE_ENV=production
ENV PORT=3000


# Expose the application port
EXPOSE 3000


# Start the application
CMD ["npm", "start"]

Environment Variables Reference

VariableDefaultDescription
PORT3000Server port
NODE_ENVproductionNode environment
DATABASE_PATH/app/dataPath to database files
JWT_SECRET-Secret for JWT tokens (if auth enabled)
ENABLE_AUTHfalseEnable user authentication

Deploying Our Shopping List on Klutch.sh

Follow these steps to deploy your shopping list app:

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial Our Shopping List configuration"
    git remote add origin https://github.com/yourusername/shopping-list-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 “shopping-list” or “groceries”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    Configure your shopping list instance:

    VariableValue
    NODE_ENVproduction
    PORT3000

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /app/data1 GBDatabase and application data

    Deploy Your Application

    Click Deploy to start the build process.

    Access Our Shopping List

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

Initial Setup

Creating Your First List

On first access:

  1. Navigate to your shopping list URL
  2. Click “Create New List” or the + button
  3. Name your list (e.g., “Groceries”, “Costco”)
  4. Start adding items

Adding Items

Add items to your list:

  1. Type the item name in the input field
  2. Press Enter or click Add
  3. Optionally specify quantity and category
  4. Items appear in the list immediately

Organizing by Category

Group items by category:

  1. Assign categories when adding items
  2. Categories group items together
  3. Custom categories can be created
  4. Helps navigate large lists efficiently

Sharing Lists

Share lists with family:

  1. Open the list you want to share
  2. Click the Share button
  3. Copy the generated link
  4. Send to family members

Joining Shared Lists

To join a shared list:

  1. Open the share link
  2. The list opens in your browser
  3. Install as PWA for easy access
  4. Changes sync in real-time

Real-Time Collaboration

When sharing lists:

  • Items added by one person appear for everyone
  • Checked-off items update in real-time
  • Multiple people can edit simultaneously
  • Changes persist when offline, sync when connected

PWA Installation

Installing on iPhone/iPad

  1. Open your shopping list in Safari
  2. Tap the Share button
  3. Select “Add to Home Screen”
  4. Name the app and tap Add
  5. Access from your home screen like a native app

Installing on Android

  1. Open your shopping list in Chrome
  2. Tap the menu (three dots)
  3. Select “Add to Home Screen” or “Install App”
  4. Follow the prompts
  5. Access from your home screen

Desktop Installation

  1. Open in Chrome or Edge
  2. Click the install icon in the address bar
  3. Confirm installation
  4. Access from your applications

Using the Shopping List

Shopping Workflow

Typical shopping workflow:

  1. At Home: Add items as you run out
  2. Before Shopping: Review and organize the list
  3. At the Store: Check off items as you shop
  4. After Shopping: Clear completed items

Checking Off Items

Mark items as purchased:

  1. Tap an item to check it off
  2. Item moves to completed section
  3. Unchecked items remain visible
  4. Clear all completed items when done

Editing Items

Modify existing items:

  1. Tap the edit button on an item
  2. Change name, quantity, or category
  3. Save changes
  4. Updates sync to all devices

Deleting Items

Remove items from the list:

  1. Swipe left on an item (mobile)
  2. Or click the delete button
  3. Item is removed from the list
  4. Removal syncs to all devices

Advanced Features

Multiple Lists

Manage different shopping needs:

  • Grocery List: Regular weekly shopping
  • Costco List: Bulk shopping items
  • Hardware Store: Home improvement projects
  • Party List: Event-specific shopping

Item Categories

Organize items by store section:

  • Produce
  • Dairy
  • Meat
  • Frozen
  • Pantry
  • Household
  • Personal Care

Recurring Items

For items you buy regularly:

  1. Create a template list
  2. Copy items to your active list
  3. Modify quantities as needed

Authentication (Optional)

Enabling Authentication

For private lists:

  1. Set ENABLE_AUTH=true in environment variables
  2. Configure JWT_SECRET
  3. Restart the application
  4. Users must log in to access lists

User Registration

With authentication enabled:

  1. Users register with email/password
  2. Each user has private lists
  3. Sharing requires authentication
  4. Lists are protected from public access

Backup and Restore

Backing Up Data

Back up your shopping list data:

  1. Access the persistent volume
  2. Copy the database file
  3. Store in a secure location

Restoring Data

To restore from backup:

  1. Stop the application
  2. Replace the database file
  3. Restart the application
  4. Data is restored

Troubleshooting Common Issues

Sync Not Working

Symptoms: Changes not appearing on other devices.

Solutions:

  • Check internet connectivity
  • Verify WebSocket connections are allowed
  • Try refreshing the page
  • Check server logs for errors

PWA Not Installing

Symptoms: Install option not appearing.

Solutions:

  • Ensure HTTPS is working (required for PWA)
  • Try a different browser
  • Clear browser cache
  • Check service worker registration

Offline Mode Issues

Symptoms: App not working without internet.

Solutions:

  • Ensure PWA is installed (not just bookmarked)
  • Check service worker is registered
  • Clear app cache and reinstall
  • Verify offline support is enabled

Data Not Persisting

Symptoms: Lists disappear after restart.

Solutions:

  • Verify persistent volume is mounted
  • Check volume path matches database path
  • Review application logs for database errors
  • Ensure sufficient disk space

Additional Resources

Conclusion

Deploying Our Shopping List on Klutch.sh provides a simple, private shopping list solution for your family. With real-time sync, offline support, and PWA installation, Our Shopping List works smoothly for everyday use.

The combination of persistent storage, reliable uptime, and HTTPS security makes Klutch.sh well-suited for hosting Our Shopping List. Your shopping data stays private on your infrastructure while remaining accessible from any device.

Install the PWA on your family’s devices and start collaborating on your shopping lists today.