Share your altero setup

[eseifert]

Running altero somewhere interesting? Please show us how you deployed it.

This category is for configurations and integrations that might help other users, including:

• Docker Compose setups
• Caddy, nginx, or Traefik configurations
• NixOS modules
• Unraid or TrueNAS deployments
• Kubernetes manifests
• systemd services
• PostgreSQL setups
• OIDC or SAML integrations
• backup strategies
• monitoring
• institutional deployments

A useful post might include:

• what you are running altero on
• why you chose that setup
• any configuration snippets you can safely share
• problems you encountered
• anything you would do differently next time

Please remove passwords, API keys, private hostnames, and other secrets before posting configuration.

The aim is to build a collection of real-world deployment examples so new users do not have to solve the same infrastructure problems independently.

Even a small home-server setup is worth sharing.

[ScatteredComet]

[eseifert]

Thank you so much for the feedback! Several of the things you hit are real defects, so let me go through them.

The password is a documentation bug: altero user add does not set a password, and the getting-started page then tells you to sign in with the account you just made. Creating that account closes the one door that needs no password: on an empty instance the browser lets the first account register itself and makes it the administrator, and user add is what shuts that window. So the documented path produces an account that cannot sign in and a registration form that now refuses. You found the right way out: altero user password <name>. Both paths will be named on the getting-started page, and user add will print the follow-up command.

The cryptic error: "This request is for the account …, not for yours" means what you suspected. When Zotero links an account it sends the numeric userID its data directory last synced under, and altero refuses to hand a key to a different account, because the desktop client reacts to a changed userID by offering to reset the data directory and quitting. Your profile was sending its zotero.org user id, which is not an account here, and the message says "not for yours" as though somebody else owned it, when in fact nobody does. I will change that message.

Moving the data directory aside is one way out. The other is to create the account with that same number:

altero user add default --id <the number in the message>

Zotero then finds the account it expects and the profile carries on. It is also how altero migrate zotero keeps an already-synced client in place. The client connection guide now covers this account-number requirement. For moving an existing library, follow data transfer.

Your container is reporting unhealthy: The image's HEALTHCHECK has 8000 compiled into it, so ALTERO_PORT=8090 breaks it; podman healthcheck run altero will say so. Nothing in your setup depends on it, which is why you would not have noticed. That is a real bug in the image and it is being fixed to read ALTERO_PORT.

Storage permissions: The image runs as UID 10001, and /data is given to it at build time. A bind mount arrives with the host's ownership instead, which is why drwxrwxrwx is what made it work. Under rootless Podman the incantation is podman unshare chown -R 10001:10001 /storage/altero/storage, and on SELinux systems the volume wants :Z. None of that is written down: UID 10001 does not appear in the documentation at all. Both are being fixed, with a short Podman section.

magicDNS: That was not PostgreSQL. The ports field in oci-containers is a host binding and takes an address rather than a name. Container to container you were already using the network alias altero-db, which is why the database half worked.

PostgreSQL 16 against 18: This is fine. Just as a note when you move to 18: The image keeps its files in a major-version subdirectory, which is why compose.yaml mounts /var/lib/postgresql and not /var/lib/postgresql/data. Your config is right for 16, a major upgrade is a dump and restore either way, and the container refuses to start rather than adopt a 16 volume silently.

On the documentation: Your criticism is valid and I didn’t find it harsh. The setup path is scattered: the password step is missing, the userID trap sits on a page about testing with two clients, and nothing says where 8000 comes from. Those are being fixed and a Podman section is going in. I would rather not promise a video right now.

If you don’t mind, I will link this post from the deployment page as the Podman and NixOS example.

Two things I would still like to know, since you are the first person to run it and give feedback here: which Zotero version and which desktop operating system, and whether it holds up with a second machine syncing, attachments and the streaming connection over the tailnet especially.

[eseifert]

Current Podman setup and health-check guidance is in Deployment, with a rootless test procedure and recorded result. The explanation below records the earlier image-format problem.

Yes, sorry, I was wrong about the health check: it’s in the image, but Podman does not read it.

I pulled the digest you are running and docker inspect reports the HEALTHCHECK, so the image is built correctly and your setup is not at fault. The cause is the media type. A health check is a Docker-format field; the OCI image configuration format has no equivalent. This image is built with buildx and published with OCI media types, and buildx writes the health check into the OCI configuration as an extra field. Docker reads that field. Podman parses OCI configurations into a structure that has no health check in it, so it reports that the image defines none.

The fix is to publish the image with Docker media types so the field is read back. I will verify that under Podman before releasing it. Two related items: deployment.md states that the container health check follows ALTERO_PORT, which works under Docker but not under Podman, and will be corrected; and in alpha.2 the check still has port 8000 hard-coded, with the ALTERO_PORT version on master and not yet released.

Until then, Podman accepts a health check on the command line, which NixOS passes through:

extraOptions = [
    "--network=altero-net"
    "--health-cmd=python -c \"import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:${alteroPort}/health',timeout=4).status==200 else 1)\""
    "--health-interval=30s"
    "--health-start-period=10s"
    "--health-retries=3"
];

/health opens a database connection, so it fails when PostgreSQL is unreachable rather than reporting a server that can only return errors. Nothing in your configuration depends on it; it matters when something restarts the container or waits for it to become ready.

The 8000/tcp in your podman ps output comes from the image's EXPOSE. With ALTERO_PORT=8090 nothing listens on it.

For the two-machine test, the points most likely to cause trouble:

• The second profile will hit the same account refusal. If Zotero on the other machine has synced with zotero.org, it remembers that numeric id and sends it, and default here already has a different id. The remaining option is the one you used: move that data directory aside and start from an empty one, which then pulls the library down from altero.
• Attachments in both directions. Add a PDF on one machine, sync both, open it on the other. Files use the same connection as the metadata; the server limit is 1 GB per file.
• The streaming connection. With extensions.zotero.streaming.url set on both, a change on one machine should appear on the other without a manual sync. It is a long-lived WebSocket, so anything on the path that times out idle connections will show up as updates arriving only when you sync by hand.
• Deletions. Trash an item on one machine, sync both, and check that it does not reappear on the next sync.
• Conflicts. Edit the same item's title on both machines with one offline, then sync both, and note what Zotero offers.

Whenever you get to it. A report that nothing went wrong is also useful.

[eseifert]

You've already spent much more time testing this than I could reasonably ask of you, and I'm sorry altero ended up wasting your time.

You’re wrong about the AI though. Yes, I use LLMs for implementation, but I review all code and I write replies here myself.

The bug you hit is fixed in Git and I will release another alpha version soon.

arXiv wasn't altero. It only makes outbound requests to zotero.org and a configured OIDC provider.

Thanks for the setup write-up and the bug reports, and no hard feelings if you’re done with it.