Deploying Teikei

Introduction

Teikei is an open-source platform for mapping community-supported agriculture (CSA) initiatives. The name comes from the Japanese word for “partnership” and represents the collaborative relationship between farmers and consumers in CSA models. Teikei provides an interactive map where farms, depots, and initiatives can be discovered by people looking to participate in local food systems.

Built with modern web technologies, Teikei enables communities to create their own CSA directory, helping connect people who want fresh, local food with the farmers who grow it. The platform supports multiple types of entries including farms, distribution depots, and community initiatives.

Key highlights of Teikei:

• Interactive Mapping: Visual map interface for discovering CSA opportunities
• Multiple Entry Types: Support for farms, depots, and initiatives
• Search Functionality: Find CSAs by location, products, or name
• User Accounts: Allow farmers and initiatives to manage their listings
• Multi-Language Support: Internationalization for global use
• Responsive Design: Works on desktop and mobile devices
• API Access: RESTful API for integrations
• Self-Hosted: Complete control over your community’s data
• Open Source: Community-driven development

This guide walks through deploying Teikei on Klutch.sh using Docker, configuring the database, and setting up the platform for your community.

Why Deploy Teikei on Klutch.sh

Deploying Teikei on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Teikei without complex orchestration. Push to GitHub, and your CSA platform deploys automatically.

Persistent Storage: Attach persistent volumes for your database and uploaded images. Your community data survives container restarts and redeployments.

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

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

Always-On Availability: Your CSA directory remains accessible 24/7, essential for community members looking for local food options.

Scalable Resources: Allocate CPU and memory based on your community size and traffic patterns.

Custom Domains: Assign a custom domain for your regional CSA network.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Teikei configuration
• Basic familiarity with Docker and containerization concepts
• A PostgreSQL database (or plan to deploy one)
• (Optional) A custom domain for your Teikei instance
• (Optional) Mapbox API key for enhanced mapping features

Preparing Your Repository

To deploy Teikei on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

teikei-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine AS builder

# Install git and build dependencies
RUN apk add --no-cache git python3 make g++

# Clone the repository
RUN git clone https://github.com/teikei/teikei.git /app

WORKDIR /app

# Install dependencies
RUN npm ci
RUN npm run build

# Production image
FROM node:18-alpine

WORKDIR /app

COPY --from=builder /app .

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Database configuration
ENV DATABASE_URL=${DATABASE_URL}

# Mapbox configuration (optional)
ENV MAPBOX_ACCESS_TOKEN=${MAPBOX_ACCESS_TOKEN}

EXPOSE 3000

CMD ["npm", "start"]

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
NODE_ENV	No	production	Application environment
PORT	No	3000	Application port
MAPBOX_ACCESS_TOKEN	No	-	Mapbox API key for enhanced maps
SESSION_SECRET	Yes	-	Secret for session encryption
MAIL_HOST	No	-	SMTP server for notifications
MAIL_PORT	No	587	SMTP port
MAIL_USER	No	-	SMTP username
MAIL_PASS	No	-	SMTP password

Deploying Teikei on Klutch.sh

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

Set Up PostgreSQL Database

Teikei requires PostgreSQL. You can either:

• Use a managed PostgreSQL service
• Deploy PostgreSQL as a separate app on Klutch.sh

Ensure you have your database connection string ready.

Push Your Repository to GitHub

Initialize your repository and push to GitHub. Ensure your Dockerfile is in the root of your repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “teikei” or “csa-map”.

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 Teikei Dockerfile.

Configure HTTP Traffic

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

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
DATABASE_URL	Your PostgreSQL connection string
SESSION_SECRET	A random, secure string
NODE_ENV	production
MAPBOX_ACCESS_TOKEN	Your Mapbox token (optional)

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/uploads	5 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 Teikei container
• Provision an HTTPS certificate

Run Database Migrations

After deployment, you may need to run database migrations. This can be done through the application’s initialization process.

Access Teikei

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

Initial Configuration

Setting Up Entry Types

Configure the types of entries your platform will support:

1. Farms: Agricultural operations offering CSA shares
2. Depots: Collection and distribution points
3. Initiatives: Community organizations and projects

Adding Your First Entries

Begin populating your map:

1. Register an account on your Teikei instance
2. Navigate to add a new entry
3. Fill in location, contact information, and description
4. Add products offered and pickup details
5. Submit for review (if moderation is enabled)

Customizing the Map

Configure map settings:

1. Set the default map center for your region
2. Configure zoom levels
3. Customize marker styles if needed

Managing Your Platform

User Management

Handle user accounts and permissions:

• Approve new registrations
• Manage entry ownership
• Handle content moderation

Content Moderation

Maintain quality listings:

• Review new entries before publishing
• Update outdated information
• Remove inactive listings

Analytics

Track platform usage:

• Monitor visitor patterns
• Identify popular search terms
• Measure community engagement

Production Best Practices

Security Recommendations

• Strong Secrets: Use cryptographically random session secrets
• Database Security: Use strong database credentials and secure connections
• Regular Updates: Keep your deployment updated

Performance Optimization

• Database Indexing: Ensure geographic queries are properly indexed
• Image Optimization: Optimize uploaded images for web delivery
• Caching: Implement caching for frequently accessed data

Backup Strategy

• Database Backups: Regularly back up your PostgreSQL database
• Image Backups: Back up user-uploaded images
• Configuration Export: Document your configuration settings

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container crashes on startup.

Solutions:

• Verify database connection string is correct
• Check that all required environment variables are set
• Review logs for specific error messages

Map Not Loading

Symptoms: Map area shows blank or errors.

Solutions:

• Verify Mapbox API key is valid (if using Mapbox)
• Check browser console for JavaScript errors
• Ensure map tiles are accessible

Database Connection Issues

Symptoms: Application errors related to database.

Solutions:

• Verify PostgreSQL is running and accessible
• Check connection string format
• Ensure database user has proper permissions

Additional Resources

• Teikei GitHub Repository
• Teikei Network
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Teikei on Klutch.sh gives you a powerful platform for connecting your community with local food sources. The combination of Teikei’s mapping capabilities and Klutch.sh’s deployment simplicity means you can focus on building your CSA network rather than managing infrastructure.

Whether you’re starting a new regional CSA directory or expanding an existing network, Teikei on Klutch.sh provides a reliable, always-available platform that helps farmers and consumers find each other and build lasting partnerships around local food.