Deploying Bar Assistant

Bar Assistant is a powerful, open-source cocktail recipe management platform designed specifically for home bar enthusiasts and professional bartenders alike. Unlike generic recipe management software, Bar Assistant is purpose-built for managing cocktails with features like ingredient tracking, automatic ABV calculations, unit conversions, and smart recommendations based on your available ingredients.

Why Bar Assistant?

Bar Assistant offers a comprehensive suite of features tailored for cocktail management:

• 500+ Pre-loaded Recipes: Start with an extensive library of cocktail recipes with detailed information
• Ingredient Management: Track 250+ base ingredients with categories, substitutes, and variations
• Smart Shelf: See what cocktails you can make based on ingredients you have on hand
• Multi-Bar Support: Manage multiple bars with different members and roles
• Powerful Search: Fast search powered by Meilisearch with advanced filtering by ABV, tags, glass types, and more
• Recipe Import: Import recipes from URLs, JSON, YAML, or custom collections
• Shopping Lists: Automatically generate shopping lists based on missing ingredients
• Price Tracking: Calculate cocktail costs based on ingredient prices
• SSO Support: Single sign-on integration with OAuth providers
• API & PWA: Full REST API support and Progressive Web App for mobile access

With over 900 GitHub stars and an MIT license, Bar Assistant has become a go-to solution for cocktail enthusiasts who want complete control over their recipe management.

Architecture Overview

Bar Assistant consists of multiple services that work together:

Service	Description	Docker Image
Bar Assistant API	Laravel-based backend server	barassistant/server:v5
Salt Rim	Vue.js web client	barassistant/salt-rim:v4
Meilisearch	Search engine for fast filtering	getmeili/meilisearch:v1.15
Redis (Optional)	Caching and session storage	redis:latest

Multi-Service Deployment

Bar Assistant requires deploying multiple interconnected services. Each service should be deployed as a separate app within the same Klutch.sh project for proper internal networking.

Prerequisites

Before deploying Bar Assistant, ensure you have:

• A Klutch.sh account
• A GitHub account for repository access

Deploying Bar Assistant

1. Create a New Project

   Log in to your Klutch.sh dashboard at klutch.sh/app and create a new project for your Bar Assistant deployment. Using a single project allows all services to communicate internally.

2. Deploy Meilisearch

   First, deploy the Meilisearch search engine:

   Create a new app within your project using the following Docker image:

   getmeili/meilisearch:v1.15

   Configure these environment variables:

   Variable	Description	Example
   MEILI_NO_ANALYTICS	Disable analytics	true
   MEILI_MASTER_KEY	Master API key (make it long and secure)	your-secure-master-key-at-least-16-chars
   MEILI_ENV	Environment mode	production

   Add a persistent volume for search data:

   Mount Path	Recommended Size
   /meili_data	2GB

   Configure your app to use HTTP traffic on port 7700.

   Secure Your Master Key

   The MEILI_MASTER_KEY must be at least 16 characters long. Use a strong, randomly generated key and save it—you’ll need it for the API server configuration.

3. Deploy Redis (Optional but Recommended)

   For better performance with caching and session management, deploy Redis:

   Create a new app using the Docker image:

   redis:latest

   Configure a persistent volume:

   Mount Path	Recommended Size
   /data	1GB

   Configure your app to use TCP traffic on port 6379.

   Note the internal hostname for your Redis app—you’ll need it for the API server.

4. Deploy Bar Assistant API Server

   Create a new app for the API server using:

   barassistant/server:v5

   Configure these environment variables:

   Variable	Description	Example
   APP_NAME	Application name	Bar Assistant
   APP_ENV	Environment mode	production
   APP_DEBUG	Debug mode (disable in production)	false
   APP_URL	Public URL of your API server	https://bar-api.example-app.klutch.sh
   LOG_CHANNEL	Logging output	stderr
   LOG_LEVEL	Log verbosity	warning
   DB_CONNECTION	Database driver	sqlite
   DB_FOREIGN_KEYS	Enable foreign key constraints	true
   MEILISEARCH_HOST	Internal Meilisearch URL	http://your-meilisearch-app:7700
   MEILISEARCH_KEY	Meilisearch master key	your-secure-master-key
   ALLOW_REGISTRATION	Allow new user registrations	true

   If using Redis, add these additional variables:

   Variable	Value
   REDIS_HOST	Your Redis app internal hostname
   REDIS_PORT	6379
   CACHE_DRIVER	redis
   SESSION_DRIVER	redis

   If not using Redis, use these values instead:

   Variable	Value
   CACHE_DRIVER	file
   SESSION_DRIVER	file

   Add a persistent volume for application data:

   Mount Path	Recommended Size
   /var/www/cocktails/storage/bar-assistant	5GB

   Configure your app to use HTTP traffic on port 8080.

5. Deploy Salt Rim Web Client

   Finally, deploy the web frontend:

   Create a new app using:

   barassistant/salt-rim:v4

   Configure these environment variables:

   Variable	Description	Example
   API_URL	Public URL of your Bar Assistant API	https://bar-api.example-app.klutch.sh
   MEILISEARCH_URL	Public URL of your Meilisearch instance	https://bar-search.example-app.klutch.sh

   Configure your app to use HTTP traffic on port 8080.

   URL Configuration

   The API_URL and MEILISEARCH_URL must be the public URLs accessible from the user’s browser, not internal service URLs. These are used by the frontend JavaScript running in the browser.

6. Verify Deployment

   Once all services are deployed:

   1. Access your Salt Rim web client URL (e.g., https://bar-client.example-app.klutch.sh)
   2. Click Register to create your first admin account
   3. Create a new bar and optionally import the included cocktail data
   4. Start managing your cocktail recipes!

Initial Setup

Creating Your First Bar

After registering your account:

1. Click Create Bar on the dashboard
2. Enter a name for your bar
3. Choose whether to import the default cocktail and ingredient data (recommended)
4. Click Create

The initial data import includes over 500 cocktails and 250 ingredients to get you started.

Managing Your Shelf

To track which cocktails you can make:

1. Go to the Ingredients page
2. Search for ingredients you have
3. Click Add to shelf for each ingredient
4. Go to Cocktails and filter by “Cocktails I can make”

Importing Recipes

Bar Assistant supports multiple import methods:

• URL Import: Paste a cocktail recipe URL and Bar Assistant will attempt to scrape the data
• JSON/YAML Import: Import recipes in structured formats
• Collection Import: Import entire recipe collections

Sample Docker Compose for Local Development

For local development and testing before deploying to Klutch.sh:

version: '3.8'

volumes:
  bar_data:
  meilisearch_data:

services:
  meilisearch:
    image: getmeili/meilisearch:v1.15
    environment:
      - MEILI_NO_ANALYTICS=true
      - MEILI_MASTER_KEY=your-development-master-key
      - MEILI_ENV=development
    volumes:
      - meilisearch_data:/meili_data
    ports:
      - "8081:7700"

  redis:
    image: redis
    environment:
      - ALLOW_EMPTY_PASSWORD=yes

  bar-assistant:
    image: barassistant/server:v5
    depends_on:
      - meilisearch
      - redis
    environment:
      - APP_URL=http://localhost:8082
      - MEILISEARCH_KEY=your-development-master-key
      - MEILISEARCH_HOST=http://meilisearch:7700
      - REDIS_HOST=redis
      - CACHE_DRIVER=redis
      - SESSION_DRIVER=redis
      - ALLOW_REGISTRATION=true
    volumes:
      - bar_data:/var/www/cocktails/storage/bar-assistant
    ports:
      - "8082:8080"

  salt-rim:
    image: barassistant/salt-rim:v4
    depends_on:
      - bar-assistant
    environment:
      - API_URL=http://localhost:8082
      - MEILISEARCH_URL=http://localhost:8081
    ports:
      - "8080:8080"

Save as docker-compose.yml and run:

docker-compose up -d

Access the web client at http://localhost:8080.

Advanced Configuration

Email Configuration

To enable email features like password resets:

Variable	Description
MAIL_MAILER	Mail driver (e.g., smtp)
MAIL_HOST	SMTP server hostname
MAIL_PORT	SMTP port (e.g., 587)
MAIL_USERNAME	SMTP username
MAIL_PASSWORD	SMTP password
MAIL_ENCRYPTION	Encryption type (tls or ssl)
MAIL_FROM_ADDRESS	Sender email address
MAIL_FROM_NAME	Sender name
MAIL_REQUIRE_CONFIRMATION	Require email confirmation

SSO/OAuth Setup

Bar Assistant supports single sign-on with various OAuth providers. Refer to the official SSO documentation for provider-specific configuration.

AI Integration

Bar Assistant can integrate with AI services for recipe recommendations. See the AI setup guide for configuration options.

User Roles

Bar Assistant includes a comprehensive role system:

Role	Permissions
Bar Owner	Full control, can delete the bar
Admin	Complete access except bar deletion
Moderator	Manage cocktails, ingredients, and bar settings
General	Create and manage own cocktails and ingredients
Guest	View, favorite, and rate recipes only

Additional Resources

• Bar Assistant Documentation - Official documentation
• Bar Assistant GitHub - API server source code
• Salt Rim GitHub - Web client source code
• Public Recipe Data - Community-maintained recipe repository
• OpenAPI Specification - API documentation
• Bar Assistant Demo - Live demo instance