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]

NixOS & Podman setup

This is a very cool app; I don't want to send my notes etc to some unknown zotero.org server all the time but I still want to sync my zotero between devices. And afaik altero is the only neat way of doing this atm (?) if you want data + attachments (obvs can use webdav for attachments only, but then it still forces you to sign in to zotero, ugh). Below is the steps I followed to set this up on a nix homelab. I tried to build it from source a few times, but I couldn't get uv / python deps to work nicely, so I just decided to use podman.

I haven't tested it on multiple machines yet, this is just how I got altero actually running on my server and read/writeable from my desktop.

The actual setup

The setup is probably awful and not very canonical, I don't really understand docker / podman or postgres, but at least it runs.

altero.nix (place in homelab config)

{ myLib, pkgs, ... }:
let
  alteroPort = "8090";
  home-server-ip = "<your server ip>"; # didn't seem to work with a magicDNS, idk maybe postgres requires raw ips :(

  internal-storage-path = "/data/storage";
  external-storage-path = "/storage/altero/storage";

  internal-database-path = "/var/lib/postgresql/data";
  external-database-path = "/storage/altero/database";

  postgresPassword = "change-this-password"; # maybe change this or put it in agenix etc :)
  postgresPort = "5432";
in
{
  virtualisation.oci-containers.backend = "podman";

  systemd.services.podman-network-altero-net = {
    serviceConfig.Type = "oneshot";
    wantedBy = [
      "podman-altero.service"
      "podman-altero-db.service"
    ];
    script = ''
      ${pkgs.podman}/bin/podman network exists altero-net || ${pkgs.podman}/bin/podman network create altero-net
    '';
  };

  virtualisation.oci-containers.containers = {
    altero-db = {
      image = "postgres:16-alpine";
      extraOptions = [ "--network=altero-net" ];
      environment = {
        POSTGRES_DB = "altero";
        POSTGRES_USER = "altero";
        POSTGRES_PASSWORD = postgresPassword;
      };

      volumes = [
        "${external-database-path}:${internal-database-path}"
      ];
    };

    altero = {
      image = "ghcr.io/eseifert/altero:1.0.0-alpha.2@sha256:0e21bcb764f155330e74f6d8dfae79b40ba352a044ee1eb073b5c73fb39cde8d";
      extraOptions = [ "--network=altero-net" ];
      ports = [ "${home-server-ip}:${alteroPort}:${alteroPort}" ];
      environment = {
        ALTERO_DATABASE_URL = "postgresql+asyncpg://altero:${postgresPassword}@altero-db:${postgresPort}/altero";
        ALTERO_PORT = "${alteroPort}";
        ALTERO_HOST = "0.0.0.0";
        ALTERO_STORAGE_PATH = internal-storage-path;
        ALTERO_PUBLIC_URL = "http://home-server.${myLib.tailnetName}:${alteroPort}";
      };

      volumes = [
        "${external-storage-path}:${internal-storage-path}"
      ];

      dependsOn = [ "altero-db" ];
    };
  };
}

(I had something on port 8000 already, so I moved it to 8090)

This will fail as the directories don't exist, so either add the directories to systemd.tmpfile.rules or just create them, here's my permissions (yes my storage perms are awful, but i just wanted something running and i couldnt work out what users actually need access when running from podman / altero)

drwx------ 19   70 root 4096 Sep 11 17:44 database
drwxrwxrwx  4 root root 4096 Sep 11 18:30 storage

Next up is to create a user, the website docs don't mention passwords but it seems like the app might require one, idk, anyway I ran

sudo podman exec -it altero altero user add default
sudo podman exec -it altero altero user list
[new user named 'default' should be here]
sudo podman exec -it altero altero user password default
[input the pw you want]

Now go Settings -> Advanced -> Config Editor (right at the bottom) in your Zotero app, and add in

extensions.zotero.api.url = http://[your-server-ip]:8090/
extensions.zotero.streaming.url = ws://[your-server-ip]:8090/stream

Now, idk how to actually remove the username cache from ~/Zotero (or wherever your library is), so I just created a new folder i.e.

Move ~/Zotero -> ~/Zotero.backup
mkdir ~/Zotero

(otherwise altero would open, but zotero would request a specific user, presumably my zotero account username, which then led to an error, see below)

Then I reopened it, its obviously all empty, clicked sync and altero opened. It prompted me for the pw for default, which I input. Then it all just worked :)

(At least for now)

A very important note is that I also have daily backups of ~/Zotero, so I'm okay with the corruption etc risk from altero being new, syncing is just a nice bonus for me anyway. So I will probably turn automatic syncing off and only sync before / after using my laptop for bit, or travelling, etc.

Some Issues & Feedback

I've tried for hours to get this running on nix, its very very difficult for me (even with podman or docker). Lots of steps are not explained in a beginner friendly way. There are a few times where the docs ref magic variables (like port 8000) implicitly, where it might be more helpful to use a variable that links to a definition, or at least state the purpose of what its doing. (Part of this is just me being new to podman and not understand ports within and outside of containers)

The main issue I found with the docs is the most important things to actually get altero set up are scattered all over the place. I think it would really benefit from a single page that concisely summarises (written by a human who has done the process themself) how to setup altero on a server, setup a local app, connect to it, and use it. Altero is actually quite simple and doesnt have many things to setup (my nix file is like 80 lines long), but the docs felt like a very large website that was confusing to parse. Like it just doesnt feel that the flow of the docs matches the flow of the setup process.

Maybe a youtube tutorial would be good, including how to setup the podman/docker containers, and the users. Like from nothing to zotero setup fully with altero in one video. e.g. do I create the user and pw via the cli, or on the website? Its not obvious from the docs (I assume either is allowed, but these things should probably be stated somewhere)

Also I got an error "This request is for the account "user ...", not for yours" which was a bit cryptic: I think this should maybe be changed to "This request to connect Zotero to altero is for a user not found in the altero database. Have you cleared references to your old Zotero account?" (okay maybe not so verbose, but something to that effect). Maybe all zotero account ids are this long, in which case you could just check for that and alert the user that their zotero app has an old username in its cache.

[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. This is documented in administration.md and web/data-transfer.md and on neither page you were reading, which is your "scattered" complaint, so I will add it to the client page too.

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.

[ScatteredComet]

My Zotero version is 9.0.6 (64-bit) (the version packaged by nixOS 26.05 stable)

I tried checking the healthcheck thing but there isn't any healthcheck in the image? I'm confused

CONTAINER ID  IMAGE                                                                                            COMMAND     CREATED       STATUS       PORTS                                    NAMES
93071a196b7d  docker.io/library/postgres:16-alpine                                                             postgres    19 hours ago  Up 19 hours  5432/tcp                                 altero-db
2cae8f9e69aa  ghcr.io/eseifert/altero@sha256:0e21bcb764f155330e74f6d8dfae79b40ba352a044ee1eb073b5c73fb39cde8d  altero      17 hours ago  Up 17 hours  100.105.208.27:8090->8090/tcp, 8000/tcp  altero

$ sudo podman healthcheck run altero
Error: container 2cae8f9e69aa8f44db438055fe2db8271b6ffe673ed1e16812fa5032f89a7506 has no defined healthcheck

Feel free to link to this, its not perfect in any way ofc, but it'll do for now

I'll setup some syncing between 2 devices next week ish, I'll keep you updated!

[eseifert]

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.

[ScatteredComet]

I'm sorry bro, but your vibeslopped app doesn't work.

Since you are clearly just using AI to write every word here, I'm not trying any more. Thanks for getting me rate limited from arxiv :))

Here is a slop bug report (you clearly cba so I cant either)

---

Bug: 500 Error on DELETE /keys/current due to ForeignKeyViolationError
When Zotero attempts to delete an API key via DELETE /keys/current, the server crashes with a 500 error. The PostgreSQL logs show a foreign key violation:
asyncpg.exceptions.ForeignKeyViolationError: update or delete on table "api_keys" violates foreign key constraint "login_sessions_api_key_id_fkey" on table "login_sessions"
DETAIL: Key (id)=(1) is still referenced from table "login_sessions".
Proposed Fix: Add ondelete="CASCADE" to the foreign key relationship for login_sessions.api_key_id, or explicitly delete the associated login sessions before deleting the API key in the route handler.

[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.