Deploying Kinto

Introduction

Kinto is a minimalist JSON storage service with synchronization and sharing abilities. Originally developed by Mozilla, Kinto provides a simple yet powerful way to store and sync data across devices and users, making it ideal for building offline-first applications.

With a clean REST API, Kinto handles the complex problems of data synchronization, conflict resolution, and access control, letting developers focus on their application logic. The service supports multiple storage backends including PostgreSQL, Redis, and in-memory storage, giving you flexibility in deployment options.

Key highlights of Kinto:

Simple REST API: Store and retrieve JSON records with a clean HTTP interface
Synchronization: Built-in sync protocol for offline-first applications
Sharing and Permissions: Fine-grained access control for data sharing
Conflict Resolution: Automatic handling of concurrent modifications
Multiple Backends: PostgreSQL, Redis, or in-memory storage
Batch Operations: Efficiently process multiple operations in a single request
Schema Validation: Optional JSON schema validation for records
Pluggable Authentication: Support for multiple authentication methods
Event Notifications: Webhooks and push notifications on data changes
History Tracking: Optional audit trail for all modifications

This guide walks through deploying Kinto on Klutch.sh using Docker, configuring storage backends, and setting up authentication.

Why Deploy Kinto on Klutch.sh

Deploying Kinto on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds Kinto from your Dockerfile without complex configuration.

Persistent Storage: Attach volumes for PostgreSQL data or Kinto’s file-based storage.

HTTPS by Default: Secure API access with automatic SSL certificates.

GitHub Integration: Updates to your configuration trigger automatic redeployments.

Scalable Resources: Adjust resources based on data volume and traffic.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and REST APIs
(Optional) A PostgreSQL database for production deployments

Preparing Your Repository

To deploy Kinto on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

kinto-deploy/
├── Dockerfile
├── kinto.ini
└── .dockerignore

Creating the Dockerfile

FROM kinto/kinto-server:latest

# Copy custom configuration
COPY kinto.ini /etc/kinto/kinto.ini

EXPOSE 8888

Creating kinto.ini

Create a configuration file for Kinto:

[app:main]
use = egg:kinto

kinto.includes = kinto.plugins.default_bucket
                 kinto.plugins.admin

# Storage backend (using environment variables)
kinto.storage_backend = kinto.core.storage.postgresql
kinto.storage_url = ${KINTO_STORAGE_URL}

kinto.cache_backend = kinto.core.cache.postgresql
kinto.cache_url = ${KINTO_CACHE_URL}

kinto.permission_backend = kinto.core.permission.postgresql
kinto.permission_url = ${KINTO_PERMISSION_URL}

# Security
kinto.userid_hmac_secret = ${KINTO_USERID_HMAC_SECRET}

# Batch settings
kinto.batch_max_requests = 25

# CORS
kinto.cors_origins = *

# Project details
kinto.project_name = My Kinto Instance
kinto.project_docs = https://docs.klutch.sh

[server:main]
use = egg:waitress#main
host = 0.0.0.0
port = 8888

Environment Variables Reference

Variable	Required	Description
`KINTO_STORAGE_URL`	Yes	PostgreSQL URL for storage
`KINTO_CACHE_URL`	Yes	PostgreSQL URL for cache
`KINTO_PERMISSION_URL`	Yes	PostgreSQL URL for permissions
`KINTO_USERID_HMAC_SECRET`	Yes	Secret for user ID hashing

For simplified deployments, you can use the same database URL for all three backends.

Creating the .dockerignore File

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

Deploying Kinto on Klutch.sh

Set Up PostgreSQL Database

Kinto works best with PostgreSQL in production:

Use a managed PostgreSQL service
Deploy PostgreSQL on Klutch.sh

Note your connection URL: postgresql://user:password@host:5432/kinto

Generate HMAC Secret

openssl rand -hex 32

Save this for environment variables.

Push Your Repository to GitHub

git init
git add Dockerfile kinto.ini .dockerignore
git commit -m "Initial Kinto deployment configuration"
git remote add origin https://github.com/yourusername/kinto-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.

Create a New App

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

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8888

Set Environment Variables

Variable	Value
`KINTO_STORAGE_URL`	`postgresql://user:pass@host:5432/kinto`
`KINTO_CACHE_URL`	`postgresql://user:pass@host:5432/kinto`
`KINTO_PERMISSION_URL`	`postgresql://user:pass@host:5432/kinto`
`KINTO_USERID_HMAC_SECRET`	Your generated secret

Deploy Your Application

Click Deploy to start the build process.

Access Kinto

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

Using Kinto

Server Info

Check server status:

curl https://your-app-name.klutch.sh/v1/

Creating Records

Store JSON data:

# Create a record in the default bucket
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -d '{"data": {"name": "My Item", "value": 42}}' \
  https://your-app-name.klutch.sh/v1/buckets/default/collections/items/records

Retrieving Records

curl -H "Authorization: Basic dXNlcjpwYXNz" \
  https://your-app-name.klutch.sh/v1/buckets/default/collections/items/records

Batch Operations

Process multiple operations:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -d '{
    "requests": [
      {"method": "POST", "path": "/buckets/default/collections/items/records", "body": {"data": {"name": "Item 1"}}},
      {"method": "POST", "path": "/buckets/default/collections/items/records", "body": {"data": {"name": "Item 2"}}}
    ]
  }' \
  https://your-app-name.klutch.sh/v1/batch

Data Organization

Buckets and Collections

Kinto organizes data hierarchically:

Buckets: Top-level containers (like databases)
Collections: Groups of records (like tables)
Records: Individual JSON documents

Default Bucket

The default_bucket plugin provides a personal bucket for each user:

# Access automatically created with basic auth
curl -H "Authorization: Basic dXNlcjpwYXNz" \
  https://your-app-name.klutch.sh/v1/buckets/default

Authentication

Basic Authentication

Simple username/password authentication:

# Base64 encode credentials
echo -n "user:password" | base64
# Use in Authorization header
Authorization: Basic dXNlcjpwYXNzd29yZA==

Configuring Authentication

Enable specific authentication methods in kinto.ini:

# Multiple authenticators
multiauth.policies = basicauth

multiauth.policy.basicauth.use = kinto.core.authentication.BasicAuthAuthenticationPolicy

Client Libraries

JavaScript (kinto.js)

import Kinto from 'kinto';

const kinto = new Kinto({
  remote: 'https://your-app-name.klutch.sh/v1',
  bucket: 'default'
});

const collection = kinto.collection('tasks');

// Add a record
await collection.create({ title: 'Buy groceries', done: false });

// Sync with server
await collection.sync();

Python (kinto-http.py)

from kinto_http import Client

client = Client(
    server_url='https://your-app-name.klutch.sh/v1',
    auth=('user', 'password')
)

# Create a record
client.create_record(
    bucket='default',
    collection='tasks',
    data={'title': 'Buy groceries', 'done': False}
)

Production Best Practices

Database

Connection Pooling: Configure appropriate pool sizes
Backups: Regular PostgreSQL backups
Indexes: Add indexes for frequently queried fields

Security

Strong Secrets: Use long, random HMAC secrets
HTTPS Only: Always use HTTPS in production
Authentication: Enable proper authentication in production

Troubleshooting Common Issues

Database Connection Errors

Solutions:

Verify PostgreSQL URL format
Check database exists and is accessible
Ensure user has proper permissions

Permission Denied

Solutions:

Verify authentication credentials
Check bucket/collection permissions
Review access control settings

Additional Resources

Conclusion

Deploying Kinto on Klutch.sh gives you a powerful, self-hosted JSON storage service with synchronization capabilities. The combination of Kinto’s simple API and Klutch.sh’s deployment simplicity means you can quickly build offline-first applications without managing complex backend infrastructure.

Whether building mobile apps, progressive web apps, or any application needing data sync, Kinto on Klutch.sh provides the reliable foundation you need.