cmintey/wishlist: a self-hosted wishlist you share with family and friends

What cmintey/wishlist solves, and who it is actually for

The problem is narrow and seasonal: a group of people wants to buy each other gifts, and nobody wants to ask what the other person wants. Wishlist is a self-hosted application where each person keeps a list of wishes and everyone else can mark an item as claimed, so two people do not buy the same thing. The README frames the audience directly, saying that with a simple user interface "even the grandparents can get involved." That is the design target: relatives who will use the app a few times a year, not power users.

It is for people who already run a server or a NAS and are comfortable with Docker Compose. It is not a hosted service, and the repository gives no indication of a managed offering. The feature list covers claiming items, checking claimed items off as purchased, fetching product data from a URL, email invitations over SMTP, suggestions, PWA support, multiple groups, Registry Mode, and OAuth authentication. Each of those is a separate configuration decision, which is the real cost of running it.

How groups, claims and Registry Mode fit together

The unit of separation is the group. A user can belong to several, and the README states that wishes in different groups are completely separate; you switch between them from the menu behind your profile picture. Anyone can create a group, and the creator becomes its manager. A manager invites users, adds or removes existing users from the group they manage, and can delete the group. An admin holds the same permissions as a group manager, so there is no separate tier above them for group-level actions.

Registry Mode changes the shape of a group. It restricts the group to a single user with a single list, and the owner can generate a public link. People who open that link do not sign in and do not create accounts; they view items and claim them by entering an identifier such as an email address, with a name optional. The README is explicit that there is currently no way to un-claim items claimed this way. That is a one-way action, and it is the sharpest edge in the whole application. A mistyped claim by a well-meaning relative cannot be reversed through the interface.

Suggestions run the other way, letting you add items to someone else's list. Three modes exist. Approval Required queues the item until the list owner accepts it, after which they can edit or delete it. Auto Approval adds it immediately, and the owner can still edit or delete it. Suprise Me, spelled that way in the README, adds the item immediately but hides it from the list owner, who therefore cannot see, edit or delete it. That last mode is the one to think about before enabling: it deliberately removes the owner's control over their own list.

Installing cmintey/wishlist with Docker Compose

The README's getting started path is Docker Compose. You write a compose file that pulls the image from the GitHub Container Registry, maps port 3280, and mounts two volumes: one for uploaded images and one for the SQLite database. The README's own example looks like this.

services:
  wishlist:
    container_name: wishlist
    image: ghcr.io/cmintey/wishlist:latest
    ports:
      - 3280:3280
    volumes:
      - ./uploads:/usr/src/app/uploads
      - ./data:/usr/src/app/data
    environment:
      ORIGIN: http://192.168.2.10:3280
      TOKEN_TIME: 72

Start it with `docker compose up -d`, then open `http://<host>:3280`. The repository also ships a `docker-compose.yaml` at the top level that uses `env_file: .env` instead of inline environment variables, and a `.env.example` listing ORIGIN, TOKEN_TIME, DEFAULT_CURRENCY, LOG_LEVEL and MAX_IMAGE_SIZE. Copying `.env.example` to `.env` and filling in ORIGIN is the cleaner route if you prefer to keep configuration out of the compose file.

cp .env.example .env
docker compose up -d

ORIGIN is the value people get wrong. The README warns that it must be set to the URL your users connect to, otherwise you will experience issues, and notes that if the value is an IP address it must include the exposed port. TOKEN_TIME is the number of hours that signup and password reset tokens stay valid; the example uses 72. DEFAULT_CURRENCY is an ISO code applied when a product search returns no currency, and MAX_IMAGE_SIZE caps uploads in bytes, defaulting to 5000000.

Running it behind a reverse proxy, and the subpath limit

The README recommends a reverse proxy, and then immediately names a constraint: Wishlist does not support running on a different subpath. It cannot live at `https://domain.com/wishlist`. It needs its own hostname or its own port. For anyone consolidating several self-hosted services under one domain, that is a real planning constraint rather than a detail.

There is also a known issue behind Nginx and Synology NAS, which uses Nginx underneath. The README points to issue 170 and recommends setting three proxy buffer properties in the Nginx configuration.

proxy_buffer_size   128k;
proxy_buffers   4 256k;
proxy_busy_buffers_size   256k;

If you skip these and your users hit errors through the proxy, the buffer settings are the first thing to check. The repository also contains a Caddyfile, so Caddy is an option the project itself uses, though the README does not document a Caddy configuration path for users.

Invitations, SMTP and OAuth: what you can leave unconfigured

SMTP is optional. The README states plainly that it does not need to be configured for the app to function, and that without it you can still generate invite links and forgot password links manually. What SMTP buys you is email delivery of those links and the forgot password flow. A small family group can run without it and paste links into a chat.

Public signup is on by default, meaning anyone with the URL can create an account. Turning it off makes the instance invite only, which is the setting most people will want if the instance is reachable from the internet. Invitations then go out by email when SMTP is configured, or as a generated link you copy yourself when it is not.

OAuth through OpenID Connect has been available since v0.42.0. You configure it in the Wishlist Administration Settings page with an Issuer URL, a Client ID and a Client Secret; everything else is optional. The README names Authelia, Authentik, Keycloak and Google as providers that fit, and says role-based access should be handled in the identity provider rather than in Wishlist. The redirect URL to register with your provider is `https://<my_wishlist_domain>/login`. If you already run one of those providers, this removes the password reset problem entirely.

Where cmintey/wishlist is the wrong tool

The un-claim gap in Registry Mode is the clearest failure mode. A public link lets anyone with an email address claim an item, and the README says there is currently no way to undo that. If your registry will be shared widely, expect duplicate or mistaken claims that you cannot fix in the app.

The subpath restriction rules it out for anyone who wants to mount it under an existing path. The Nginx buffer issue means Synology users in particular should expect to touch their proxy configuration rather than just forwarding a port.

Scale is another boundary. Storage is SQLite in a mounted volume, and there is no mention of an external database. That is fine for a family or a friend group and wrong for anything resembling a public registry with heavy concurrent traffic. The absence of a documented rollback or export path in the README is worth noting too: if you want your data out, the README does not describe how.

Finally, the project is not positioned as a general e-commerce wishlist. There is no store integration beyond fetching product data from a URL, and no price tracking or stock alerts. If you want a shopping-oriented list tied to a retailer, this is a different kind of tool.

Alternatives: a shared spreadsheet versus a purpose-built list

The honest alternative for a small family is a shared spreadsheet or document where each person adds rows and others mark a column. It costs nothing to run, needs no server, no reverse proxy and no ORIGIN variable, and anyone who can use a browser can edit it. The difference in approach is that a spreadsheet does not hide claims from the list owner: everyone sees who marked what. Wishlist's whole mechanism is per-user visibility, where the owner of a list does not see which items have been claimed, and in Suprise Me mode does not even see items added to their own list. If that concealment is not something you need, a spreadsheet removes the deployment work entirely.

A hosted wishlist service is the other alternative, and its trade-off is the mirror image: no Docker host, no Nginx buffers, no ORIGIN misconfiguration, but your family's names, emails and gift lists sit on someone else's infrastructure. Wishlist exists precisely because some people do not want that. The choice is between operational work and data custody, and the README is written for people who have already picked the second.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent: v0.66.0 on 2026-07-08, v0.65.2 and v0.65.1 both on 2026-06-20. The README's compose example uses the `latest` tag, which means an upgrade is a pull and a restart rather than a pinned version bump. That is convenient and also the reason to pin a tag if you care about reproducing a known state.

docker compose pull
docker compose up -d

The database lives in the mounted `./data` directory and uploads in `./uploads`, so both survive a container replacement. The README does not document a migration or rollback procedure, and the repository does contain a `prisma/` directory with a `db:patch` script, which suggests schema changes ship with releases. Back up the `data` directory before pulling, because that is the only copy of the SQLite database.

Wishlist is MIT licensed. That permits commercial and private use, modification and redistribution, with the licence and copyright notice retained. It is a permissive licence with no copyleft obligation on your own code. This is a description of the licence text, not legal advice; check the LICENSE file in the repository for the exact terms.

Editorial conclusion

Adopt cmintey/wishlist if you already run a Docker host and want one private place where family and friends claim gifts without accounts for the Registry Mode public link. Skip it if you need a hosted service, a subpath deployment, or the ability to un-claim an item taken through a registry link, because that last one is documented as unavailable. Before committing, verify that ORIGIN matches the exact URL and port your users will open, confirm your reverse proxy carries the Nginx buffer settings the README lists, and decide whether SMTP is configured, since invite and password reset links otherwise have to be copied and sent by hand.

Frequently asked questions

Official sources

1. cmintey/wishlist on GitHub
2. Issues
3. License: MIT
4. README
5. Releases