Exporting to your own Immich server

What I learned

• Check a key with a request that actually needs it. One hosted Immich service answered its "about this server" request for any key at all, so a wrong key looked fine until the first upload failed.
• Let the server handle duplicates. Immich already recognises a photo it's seen before. If I'd kept my own record of what was uploaded, it would have been a second list that could fall out of sync.
• Give bigger uploads more time. A single five-minute limit per upload failed large batches on connections that were slow but working fine.
• Keep the time zone with the time. Without it, photos taken at 6 pm in California showed up in Immich at 11 am.

Why Immich

I keep my originals in folders on a drive, and that won't change. But nobody wants to browse a folder of JPEGs on their phone, and I don't want to hand my photos to a service I can't leave. Immich sits in between for me. It's a real photo library with a phone app, running on hardware I own, or on a hosted service if I'd rather not run it myself.

Before this, I had to export to a folder and then upload that folder by hand. Now it's one step.

Making whatever you type work

Everyone's server lives at a different address. Some people type photos.example.com, some paste https://photos.example.com/api/ from the docs, and some use http://nas.local:2283 on their home network. I wanted all of those to work.

First, LightPhotos tidies the address. It trims spaces, removes a trailing slash or /api, and adds https:// if you left it off. Then it asks the server's discovery file, /.well-known/immich, where its API lives. (The API is the address the app actually sends requests to.) That helps people who host Immich under a sub-path like /immich/api. If there's no discovery file, it assumes the usual /api.

If you didn't type http:// or https:// and the secure HTTPS connection fails, LightPhotos won't quietly fall back to plain HTTP. That would send your API key across the network unencrypted without telling you. Instead, the error suggests starting the address with http:// if your server really doesn't have HTTPS, and then it's your choice.

Checking the key before it matters

The obvious way to test a connection is to ask the server about itself. I tried that against Gumnut, a hosted Immich service, and it answered for any key, even one I made up. So LightPhotos asks "who does this key belong to?" instead. That only works with a real key, and it gives the form something friendly to show: "Connected as" with your name and email.

Nothing is saved until that check passes. Then the address goes into the app's settings, and the key goes somewhere safer.

• On a Mac, the key goes into your login Keychain, with one entry per server.
• On Linux, it's a file in the app's config folder that only your user can read.
• On Windows, it's a file in your own app data folder.

One small detail I'm glad I got right: LightPhotos doesn't touch the Keychain until you open the Immich tab. If you never use Immich, you'll never see a Keychain prompt.

What actually gets uploaded

Immich gets your finished photo. LightPhotos renders it exactly as it would for a folder export, with your edits, crop and size, and saves it as a JPEG. Your originals stay on your drive.

Two pieces of information go along with it:

• When it was taken. My first version read the camera's clock as if it were UTC (universal time), so a photo taken at 6 pm in California showed up in Immich at 11 am. Now each export carries its capture time plus the camera's time-zone offset, and falls back to the file's date only when the camera didn't record one.
• Your star rating, which is set right after the upload. Some keys are allowed to upload but not to change photos. With one of those, the photo still uploads and you get a warning about the rating instead of a failed export.

Running the same batch twice

Exports get interrupted. The laptop goes to sleep, or the Wi-Fi drops. The easiest fix is to run the export again, so I needed that to be safe.

Luckily, Immich already handles this. If you upload the same file twice, it replies "duplicate" and points to the photo it already has. LightPhotos keeps no list of what it's uploaded. It just sends everything again, counts the duplicates and tells you something like "Uploaded 40 photos, 32 already on the server." The batch picks up where it left off, and I didn't have to write any bookkeeping for it.

Slow uploads that are still working

Home internet is usually slow at uploading, and LightPhotos exports several photos at once. My first version gave each upload a fixed five-minute limit. With a batch of large photos on a slow connection shared eight ways, uploads hit that limit even though the connection was fine.

Now each upload gets a minute plus extra time based on its size, worked out as if the connection were a 1 Mbit/s link split between eight uploads:

time allowed = 60 s + photo size / 16 KB per second

That gives a 25 MB photo about 28 minutes. It sounds generous, but a connection that's truly stuck still fails, because the other limits, like connecting and waiting for the server's reply, stay short.

Why it isn't in the browser

The web version of LightPhotos shows the Immich tab with a note that it only works in the desktop app. A web page can only talk to a server on another site if that server says it's allowed, and Immich doesn't. The browser blocks the request before it's even sent. The desktop app isn't a web page, so that rule doesn't apply to it.

What's next

I'm working on album support next, so you can pick an existing album or name a new one and the batch goes into it. After that, I want automatic retries for uploads that fail partway through. Servers with self-signed certificates, which are common on home networks, probably won't connect yet. If you run one, I'd like to hear whether it works for you.

If you run Immich and something here doesn't fit your setup, please tell me on the issue tracker. The desktop builds are on the downloads page.