Bar Assistant: a cocktail-specific API with a separate web client

The API is the product, the client is another repository

Bar Assistant is an all-in-one solution for managing your home bar. The README draws the distinction from other software directly: compared to recipe management software that usually tries to be more for general use, Bar Assistant is made specifically for managing cocktail recipes, and that means there are a lot of cocktail-oriented features such as ingredient substitutes, first-class ingredients, ABV calculations and unit switching.

The first structural fact is that this repository contains only the API server. The README says that if you are looking for an easy to use web client, you should take a look at Salt Rim, which is the separate Vue front end at karlomikus/vue-salt-rim.

So the project is an API and an ecosystem, not an application. There is a live API demo and a live front end demo, both under the demo.barassistant.app domain, with the credentials published in the README as [email protected] and password.

The data comes from a separate repository too. The project includes over 500 cocktail recipes with detailed information and over 250 base ingredients with categories, both from the bar-assistant/data repository, and the Dockerfile fetches that repository at build time and copies it into the resources directory. That is an interesting arrangement: the seed content is a git repository that the container downloads, so the recipe corpus is versioned separately from the code that serves it.

The primary language is PHP, the licence is MIT, the default branch is develop, and the recent releases are v6.9.0 from 2026-10-15, v6.8.1 from 2026-09-23 and v6.8.0 from 2026-09-20.

The features that only make sense for cocktails

The feature list is long, and the interesting part is the subset that would be meaningless in a generic recipe application.

There is support for custom cocktail ingredient substitutes, which is the feature that separates a cocktail model from a food model. A substitute for gin is a base spirit with a different character, and a data model that has a first-class ingredient and a substitution list can answer what you can make with what you have.

The filtering reflects that too. You can filter recipes by ABV, by base ingredient, by tags, and by whether you actually have the ingredients, which is the question a home bar actually asks. You can create a shopping list generated from the missing ingredients in your inventory, which is the same question again, answered as a list rather than a filter.

Money is modelled properly. There is support for multiple ingredient prices, automatic cocktail price calculation based on those ingredients, and a dedicated table for prices rather than a single column on the ingredient.

Then there is the long tail: glass types, utensils, tags, ingredient categories, cocktail variations, ratings, notes, user-specific collections, public bar menus, sharing recipes by public link, custom recipe images, printing, data export in various formats, recipe importing via URL, JSON, YAML or custom collections, SSO support, personal access tokens with custom permissions set by the user, statistics about recipes and user tastes, and recommendations based on favourites and tags.

The bar is a first-class object too. You can add and manage multiple bars and bar members, with fine-grained user control through user roles, so the same account can be a member of more than one bar.

Container images with no latest tag

Bar Assistant is published as a Docker image on Docker Hub and on the GitHub Container Registry, and the tagging policy is stated explicitly because there is no `latest` tag.

The README gives the four ways to refer to a version:

- `barassistant/server:v4.4.1` pulls the exact version. - `barassistant/server:v4.4` pulls the latest minor release. - `barassistant/server:v4` pulls the latest major release. - `barassistant/server:dev` pulls the latest development version, which the README marks as not recommended for production.

And the recommendation is to always use the latest major release, on the grounds that it will always be the most stable version.

That is an unusual but defensible policy. A `latest` tag that moves is a deployment that changes without anyone changing it, and for an application holding your bar inventory that is not a feature. Pinning to a major version gives you patch and minor updates on a schedule you can see, which is the behaviour most self-hosted operators want.

The `dev` tag is the escape hatch for testing a change, and it is explicitly labelled.

The image itself is built from `serversideup/php:8.4-fpm-nginx` with an s6 init system, and the Dockerfile adds the PHP extensions bcmath, intl and ffi, installs sqlite3, git and libvips42, enables opcache with a 20000 file limit, runs a production composer install with `--no-dev --no-scripts`, and stamps the version into the generated OpenAPI file with a sed substitution.

The environment variables tell you what is actually required

The environment variable table is the most useful part of the README for an operator, because it names the pieces the application cannot work without.

The infrastructure comes first. `REDIS_HOST` defaults to `redis`, `CACHE_DRIVER` defaults to `redis` with `file` as the alternative, and `SESSION_DRIVER` likewise defaults to `redis` with `file` as the alternative. That default is worth noticing, because a conventional PHP application defaults both to the file driver and this one does not. If you deploy without a Redis service and do not set those, you are asking for it to fail.

Search is Meilisearch, with `MEILISEARCH_HOST` and `MEILISEARCH_KEY`, both empty by default, and the feature list says data is automatically indexed with Meilisearch.

Access control is a set of switches. `ALLOW_REGISTRATION` defaults to true, `MAIL_REQUIRE_CONFIRMATION` defaults to false, and `ENABLE_PASSWORD_LOGIN` defaults to true, which is the one to look at if you have enabled SSO and want to close the password door behind it.

Observability is optional and scoped. `METRICS_ENABLED` defaults to false and turns on a Prometheus metrics endpoint, and `METRICS_ALLOWED_IPS` is a comma-separated list of the addresses allowed to reach it. The combination of an off-by-default endpoint and an allowlist is a sensible design, since a metrics endpoint on a public interface is an information leak.

Scraping has its own pair, `SCRAPING_HTTP_PROXY` and `SCRAPING_CLIENT_CERT`, for the recipe importing by URL feature.

And there is an AI provider block at the end: `GEN_AI_PROVIDER`, which identifies the LLM provider and supports any provider that PrismPHP supports, `GEN_AI_MODEL` for the specific model, and `GEN_AI_TIMEOUT` defaulting to 60 seconds. The mail variables follow the standard Laravel mailer shape, with `MAIL_MAILER`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_ENCRYPTION`, `MAIL_USERNAME` and `MAIL_PASSWORD`.

The local compose stack is six services

The `docker-compose.yml` in the repository root is the development environment, and it is worth reading because it shows the full shape of the application.

The `app` service builds the `dev` target with `USER_ID` and `GROUP_ID` build arguments of 1000, so the container runs as the same numeric user as the host, which is what keeps file ownership sane on a bind mount. It mounts the repository at `/var/www/cocktails` and adds a `host.docker.internal:host-gateway` entry to the extra hosts, so the container can reach services on the host.

The `horizon` service is the queue worker, with `APP_ROLE` set to `worker` and the command running the artisan horizon binary, so Laravel's queue processing and the web requests are separate containers.

The `webserver` service is `nginx:alpine` publishing port 8000 to 80, with the nginx configuration mounted from the localdev resources. Then `redis`, and `meilisearch` pinned to `getmeili/meilisearch:v1.50` with analytics disabled and a long master key, publishing 7700.

The sixth is `rustfs` on `rustfs/rustfs:latest`, publishing 9000 and 9001, with a root user and password set in the environment and a data volume. That is an object store, and its presence in the dev stack suggests images can be kept outside the container.

There is a seventh, commented out. A `metrics` service with `prom/prometheus`, a mounted prometheus configuration and a port mapping. It is present but not enabled, which matches the `METRICS_ENABLED` default of false in the environment table.

A managed instance exists, and the project says so

The README has a section on the managed instance, and it is worth reading for how the open source and commercial relationship is framed.

Bar Assistant will always be open source and MIT licensed, the README states, and then it offers the official managed instance for anyone who wants to support the project or does not want to self-host, at barassistant.app.

The distinction being made is between the licence and the hosting. The code stays MIT and the container images stay published, so self-hosting is never going to be closed off. What the managed instance sells is the operation, which for a self-hosted stack means running the app, the worker, Redis, Meilisearch and an object store, and keeping them upgraded.

The support and donations section is similarly straightforward. Bar Assistant is free, the README says, but maintaining any open source project takes time and resources, and there is a donation link. The contributing section points at `CONTRIBUTING.md`.

There is also a third-party integration, described as an unofficial Raycast extension maintained by a community member, which is a reasonable signal about the API's accessibility. There is a `SECURITY.md`, an `AGENTS.md` and an `.agents/` directory at the root, plus a `UbiquitousLanguage.md`, which is a domain glossary, and that last one is a good sign for a project that models a specialised domain.

Where Bar Assistant is the wrong choice

The first wrong case is a user who wants an application. This repository is the API server, and the front end is a separate project. A non-developer who installs the container gets an API and, at the demo instance, someone else's interface. The README is clear about this and points to Salt Rim for the client, but the gap is real for anyone who is not going to write a frontend.

The second wrong case is a generic recipe collection. The design is deliberately cocktail-specific, and the specificity is the value. If your content is a baking recipe with an oven temperature and a resting time, the substitutes, the base ingredient filtering and the ABV arithmetic are not features you need and are concepts you have to model around.

The third is a deployment with no Redis and no Meilisearch. The defaults assume Redis for both cache and sessions, and the search features need a Meilisearch host and key. You can switch the drivers to `file` and live without Redis, but then you lose the default configuration's assumptions, and Meilisearch is not optional if you want search.

The fourth is a team that wants to contribute a change to the client. The web interface is a different repository with its own build, and a change that spans the API and the interface is two pull requests.

What the project offers a developer is a data model that took real domain work: first-class ingredients, substitutions, unit switching, ABV, multiple prices per ingredient and a shopping list computed from inventory. Building that from scratch is most of the work in a cocktail application, and here it is already done and versioned.

Editorial conclusion

Bar Assistant suits a developer who wants to build a cocktail application rather than a generic recipe app, because the data model has substitutes, first-class ingredients, ABV, unit switching and multiple ingredient prices built in, and it suits a self-hosting user who will pair the API with their own frontend. It does not suit someone who wants a ready-to-use interface out of the box, since this repository contains only the API server and the Salt Rim client is a separate project, and it does not suit a deployment that wants a moving target, since the container images have no `latest` tag. Before adopting it, read the environment variable table and decide the driver choices, because `CACHE_DRIVER` and `SESSION_DRIVER` default to `redis` rather than to files, and pin the image to a specific major version rather than the `dev` tag.

Frequently asked questions

Official sources

1. karlomikus/bar-assistant on GitHub
2. License: MIT
3. Project website
4. README
5. Releases