Deploying Geeftlist

Introduction

Geeftlist is a self-hosted collaborative gift list management webapp designed to simplify and coordinate the sharing, reservation, and purchase of gifts among close ones. Born from the complexity of family gift exchanges, especially during holidays like Christmas, Geeftlist eliminates the need for slow phone calls and error-prone email chains when coordinating who is buying what.

Built with PHP, Geeftlist provides a straightforward web interface where family members can create wishlists, browse others’ lists, and secretly reserve gifts to avoid duplicates. The application maintains the surprise by hiding reservations from the gift recipient while showing them to other potential gift-givers.

Key highlights of Geeftlist:

• Wishlist Creation: Create and manage personal wishlists with items you’d like to receive
• Gift Reservation: Reserve gifts on others’ lists to prevent duplicate purchases
• Secret Reservations: Recipients can’t see who reserved their gifts, maintaining surprise
• Group Collaboration: Share lists within family groups or friend circles
• Simple Interface: Clean, easy-to-use web interface for all ages
• Self-Hosted: Keep your family’s gift data private on your own infrastructure
• No Account Required for Viewing: Optional public wishlist viewing
• Open Source: Community-driven development with transparent codebase

This guide walks through deploying Geeftlist on Klutch.sh using Docker, configuring persistent storage for your gift lists, and setting up the application for your family or group.

Why Deploy Geeftlist on Klutch.sh

Deploying Geeftlist on Klutch.sh provides several advantages for managing gift coordination:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Geeftlist without complex orchestration or manual server configuration. Push to GitHub, and your gift list platform deploys automatically.

Persistent Storage: Attach persistent volumes for your database and configuration. Your wishlists and reservations survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your gift lists from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Environment Variable Management: Securely store sensitive configuration like database credentials through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Geeftlist instance for a family-branded wishlist portal.

Always-On Availability: Your gift lists remain accessible 24/7, perfect for year-round wishlist maintenance and holiday coordination.

Private Data: Unlike commercial wishlist services, your family’s gift preferences stay on your own infrastructure.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Geeftlist configuration
• Basic familiarity with Docker and containerization concepts
• A MySQL/MariaDB database (see database deployment guides)
• (Optional) A custom domain for your Geeftlist instance

Understanding Geeftlist Architecture

Geeftlist is built on a traditional PHP web application stack:

PHP Backend: The core application runs on PHP, handling wishlist management, user authentication, and reservation logic.

MySQL/MariaDB Database: Geeftlist uses MySQL or MariaDB for storing user accounts, wishlists, items, and reservations.

Apache/Nginx Web Server: The application is served through a standard web server with PHP support.

Session-Based Auth: User authentication is handled through PHP sessions with secure password hashing.

Preparing Your Repository

To deploy Geeftlist on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

geeftlist-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM php:8.1-apache

# Install required extensions
RUN docker-php-ext-install mysqli pdo pdo_mysql

# Enable Apache rewrite module
RUN a2enmod rewrite

# Set working directory
WORKDIR /var/www/html

# Clone Geeftlist from repository
RUN apt-get update && apt-get install -y git && \
    git clone https://codeberg.org/nanawel/geeftlist.git . && \
    apt-get remove -y git && apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*

# Set permissions
RUN chown -R www-data:www-data /var/www/html && \
    chmod -R 755 /var/www/html

# Configure Apache
RUN echo '<Directory /var/www/html>\n\
    AllowOverride All\n\
    Require all granted\n\
</Directory>' >> /etc/apache2/apache2.conf

# Expose port
EXPOSE 80

CMD ["apache2-foreground"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Geeftlist requires database configuration:

Variable	Required	Default	Description
DB_HOST	Yes	-	MySQL/MariaDB host
DB_PORT	No	3306	Database port
DB_NAME	Yes	geeftlist	Database name
DB_USER	Yes	-	Database username
DB_PASSWORD	Yes	-	Database password

Deploying Geeftlist on Klutch.sh

Once your repository is prepared, follow these steps to deploy Geeftlist:

Set Up MySQL/MariaDB Database

Geeftlist requires a MySQL or MariaDB database. Deploy a database instance on Klutch.sh or use an existing database. Create a database named geeftlist.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Geeftlist deployment configuration"
git remote add origin https://github.com/yourusername/geeftlist-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. Give it a descriptive name like “geeftlist” or “family-wishlists”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Geeftlist Dockerfile.

Configure HTTP Traffic

Geeftlist serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80 (Apache’s default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
DB_HOST	Your MySQL/MariaDB host
DB_PORT	3306
DB_NAME	geeftlist
DB_USER	Your database username
DB_PASSWORD	Your database password

Attach Persistent Volumes

Add persistent storage for uploaded files:

Mount Path	Recommended Size	Purpose
/var/www/html/uploads	1 GB	User uploaded images

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Geeftlist container
• Provision an HTTPS certificate

Run Database Setup

After first deployment, access your Geeftlist instance and run the initial database setup through the web interface.

Access Geeftlist

Once deployment completes, access your Geeftlist instance at https://your-app-name.klutch.sh. Create an admin account and invite your family members.

Initial Setup and Configuration

Creating the Admin Account

On first access:

1. Navigate to the registration page
2. Create your administrator account
3. Configure basic site settings

Inviting Family Members

Add family members to your Geeftlist:

1. Share the registration URL with family
2. Or create accounts for them manually
3. Organize users into groups (e.g., “Smith Family”)

Creating Groups

Organize gift-giving circles:

1. Go to Groups in the admin panel
2. Create groups for different occasions
3. Add members to appropriate groups
4. Configure group visibility settings

Using Geeftlist

Creating a Wishlist

To add items to your wishlist:

1. Log in to your account
2. Navigate to My Wishlist
3. Click Add Item
4. Enter item details:
   • Name
   • Description
   • Link (optional)
   • Price (optional)
   • Image (optional)
5. Save the item

Browsing Others’ Lists

View what others want:

1. Navigate to a family member’s wishlist
2. Browse available items
3. Items already reserved are marked

Reserving Gifts

Claim a gift you’ll purchase:

1. Find an item on someone’s wishlist
2. Click Reserve
3. The reservation is hidden from the recipient
4. Other family members see the item is taken

Managing Reservations

Track your commitments:

1. Go to My Reservations
2. View all gifts you’ve reserved
3. Mark as purchased when complete
4. Cancel reservations if needed

Group Management

Creating Occasions

Set up gift-giving events:

Occasion	Description
Christmas	Annual family gift exchange
Birthdays	Individual birthday lists
Anniversaries	Couple gift coordination
Special Events	Weddings, graduations, etc.

Setting Deadlines

Add important dates:

1. Create an occasion with a date
2. Members receive reminders
3. Lists can be locked after deadlines

Production Best Practices

Security Recommendations

• Strong Passwords: Require strong passwords for all accounts
• HTTPS: Always access via HTTPS (provided by Klutch.sh)
• Database Security: Use strong database credentials
• Regular Updates: Keep Geeftlist updated

Family Onboarding

Tips for successful adoption:

• Start with a small group
• Provide simple instructions
• Help less technical members
• Demonstrate core features

Backup Strategy

Protect your wishlists:

1. Database Backups: Regularly back up MySQL/MariaDB
2. Before Holidays: Extra backup before major gift-giving occasions
3. Export Lists: Allow users to export their lists

Troubleshooting Common Issues

Cannot Connect to Database

Solutions:

• Verify database credentials
• Check database host accessibility
• Ensure database exists
• Review PHP error logs

Reservations Not Showing

Solutions:

• Clear browser cache
• Check user permissions
• Verify group membership
• Check database connectivity

Image Uploads Failing

Solutions:

• Check upload directory permissions
• Verify persistent volume is mounted
• Check PHP upload limits
• Review file size restrictions

Additional Resources

• Geeftlist Source Code
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Geeftlist on Klutch.sh gives you a private, self-hosted gift coordination platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Geeftlist’s collaborative features and Klutch.sh’s deployment simplicity means you can focus on celebrating with family rather than managing infrastructure.

With wishlist creation, secret reservations, and group organization, Geeftlist eliminates the chaos of holiday gift coordination. Whether you’re managing a small family or a large extended family gift exchange, Geeftlist on Klutch.sh provides a reliable, private platform that keeps everyone’s wishes organized and surprises intact.