HUB
Sign inSign up

derkezorm/nexdiary

By derkezorm

•Updated about 21 hours ago

A family diary on your own server: notes by day, the page in the evening, encrypted per person.

Image
0

901

derkezorm/nexdiary repository overview

⁠nexdiary

A diary for the family, on your own server. Jot things down during the day without minding the spelling, and in the evening turn them into a page: by yourself, or with an AI that only orders and smooths. Every person sees only their own diary; single days can be shared with people of the family, and the operator manages the accounts without ever seeing what is written in them.

nexdiary is one of the nex apps and looks like them: warm paper by day, candlelight by night, sage green (or four other colours of your choice).

Today: the notes of the day as a timeline, the values, the photos, and the button to write the day up

"Today", in the layout of a single page. The notes of the day, the question of the day, the values of 1 to 10 and the photos taken today; in the evening "Write up" turns them into a page.

⁠Screenshots

Writing a day: the editor, the cover picture, the tags and the notes beside it

Writing a page. Every day has a cover picture, a photo of your own or one of 256 drawn illustrations; a suggestion by season, time of day and tags is already chosen. The notes stay beside the page.

The journal as a blog: large cards with the newest day on top

The journal as a blog, or as a timeline by month. Search covers pages and notes.

Reading a day with its cover, its tags and the values of that day

Reading a day. A day can be shared with chosen people of the family; they read it and may give a heart, nothing more.

Statistics: streaks, a calendar of half a year, values over time and the best and worst day

Statistics, worked out on the server from your own days only: streaks, half a year as a calendar, a value over time with its seven-day average, the best and the worst day, and what seems to go together (in sentences, with the reminder that together does not mean because).

Shared with me: the days others have shared, with a heart to give back

Shared with me, and what I have shared.

My account, Look: five colours, each in light and dark The quick note on a phone

Five colours, each light and dark, kept with the account. On the phone the app starts on the quick note: one field with the keyboard open, and the notes of today above it.

More, in light and dark and on the phone, are in docs/screenshots⁠.

⁠What it does

  • Notes by day, a page in the evening. Throw down what comes to mind, with the time it came. In the evening the notes become a page in the editor, written by yourself or suggested by the AI. The notes are never changed or lost.
  • A cover picture for every day. Your own photo or one of 256 illustrations (16 motifs, four times of day, four seasons). A suggestion is already there, so a day is never without one.
  • Values from 1 to 10. Mood, health, sleep, the working day, a relationship, and your own ones. Each person decides what they rate.
  • Writing prompts. A question of the day for when nothing comes to mind, six groups that can each be switched off, and your own questions. A reminder may bring a question along.
  • Templates. Fixed headings for a page, each with a question as a hint, and one of them as your default. When the AI writes a page up it fills only what your notes say about a heading; the rest stays empty, and an empty section is dropped when you save.
  • Journal and search. The days as a blog or as a timeline by month; tags; search over pages and notes.
  • A writing goal. Once to seven times a week, as suits you. Below seven the streak counts weeks in which the goal was met; shields earned with a long streak or a long entry save a missed day or week, and a reminder can come when the week runs short.
  • Statistics. Streaks, days in the year, words, half a year as a calendar, values over time, weekdays, what goes together, the best and the worst day (30 days, a year, ever), the most frequent tags, and the same day a year ago.
  • Time capsules. A letter that opens on a chosen day, to yourself or to people in the family, written like a page and with as many photos as you like. Until the day the people it is for only see who it is from and when it opens; a letter to yourself stays sealed for you too. A push arrives on the morning it opens.
  • Looking back. A week as a strip of covers, a month as a collage, the first value as a line, the best day and what it was about; a summary by the AI only on request. The journal shows a volume per year that fills up page by page, and a year can be set as a print-ready PDF book.
  • A family question. One question a day for those who join; the others' answers open once you have answered, and stay readable on that day later. An answer is final.
  • Sharing a day. With chosen people of the family. They read the page, the photos and the attachments; values and raw notes only if you tick them. A shared day is read-only and cannot be passed on; you take it back at any time. The only reaction is a heart.
  • Photos. Upload them, or take them from your own Immich⁠ (see below). Place and camera data are removed; every photo is drawn anew from its pixels and stored sealed. Older days take photos too.
  • Attachments. Videos, voice recordings, PDFs and links go with a day, beside its photos. Videos and recordings are repacked without place or device data (ffmpeg is in the image) and play in nexdiary; a PDF opens in nexdiary's own viewer; a link is kept as it is, the server never opens it. An HEVC video from an iPhone can be converted to H.264 on the server, so it plays in every browser. Recordings are made in the browser and need https.
  • On the phone. All of it works on a phone. The quick note opens on a field and the keyboard; the app installs to the home screen with a shortcut "Note". Installed on Android with Chrome or on Windows with Edge, it takes texts, links and up to 10 photos shared from other apps, each photo as a note of its own (the iPhone does not offer sharing to web apps).
  • Reminders by Web Push, daily at your time or after a pause of a few days, not if you already wrote today.
  • Safe by default. A second factor is required from the start, passkeys, a list of signed-in devices, a notice when somebody signs in from a new device, a brake against guessing, and everything you write is encrypted in the database.
  • Around it, as in the other nex apps. Accounts by invitation, sign-in through OpenID Connect providers (several at once, a button each; a one-step setup for authentik), a log in four levels, German and English plus languages the operator adds as JSON files, backups with a check before going back, a page "About" that says when a new version is out.

⁠Start

services:
  nexdiary:
    image: ghcr.io/derkezorm/nexdiary:latest
    container_name: nexdiary
    restart: unless-stopped
    ports:
      - "127.0.0.1:8550:8000"
    volumes:
      - ./data:/data
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Berlin
docker compose up -d

Built from source instead: clone this repository, use docker-compose.yml as it is (it has build: .) and run docker compose up -d --build. The file has every option explained.

Open http://127.0.0.1:8550 on that machine (the port listens only there; the comment in docker-compose.yml⁠ says how to change that). The first account you create there is the operator. It needs the setup code from the log, so that nobody who reaches a fresh instance first can take it:

docker logs nexdiary

shows the code, new at every start until nexdiary is set up. To choose it yourself, set NEXDIARY_SETUP_TOKEN. Right after the password the account sets up its second factor; then the operator invites the others by link. Everything personal (colours, layouts, values, questions, reminders, Immich, tokens) is under "My account" for everybody; "Settings" is the operator's and holds the server.

⁠nexdiary on the internet

Many people will put nexdiary on the internet; it is made for that. Before you open it:

  1. Set it up first, from your own network, with the setup code from the log. Only then forward a port.
  2. https at a reverse proxy, and nexdiary reachable only through it: publish the port as 127.0.0.1:8550:8000 when the proxy runs on the same host, or keep both on a Docker network without a published port. Send HSTS from the proxy.
  3. Tell nexdiary about the proxy: NEXDIARY_PUBLIC_URL (the address people use), NEXDIARY_TRUSTED_PROXIES (the proxy's address or network; without it every sign-in seems to come from the proxy and the brake against guessing cannot tell people apart, and nexdiary believes no X-Forwarded-Proto) and NEXDIARY_COOKIE_SECURE: "on". NEXDIARY_TRUSTED_PROXIES is the setting for trusted proxies the authentik card means when it warns that the server receives a request as http: from a proxy named there, nexdiary takes the rightmost value of X-Forwarded-Proto (the one the proxy wrote, http or https), from anybody else none.
  4. A second factor is required from the start: right after the password every account sets one up (a code from an app, or a passkey) and keeps the recovery codes. The operator may switch the requirement off; do not.
  5. Look at "Ready for the internet?" (Settings, Sign-in). It checks the points above for itself: https, the second factor, your own account with one, the brake, the encryption, the cookies and the proxy.
  6. Save the master key (Settings, Backups, Encryption) and keep it apart from the backups. See below.
  7. Backups somewhere else, as carefully as the data folder. A backup holds every account and the server's secrets (secret.key); try a restore with "Check" now and then.
  8. Leave the switches closed that you do not need: API tokens, Immich and the AI are off until the operator opens them. Pin a version instead of latest, update on purpose, back up before.
  9. Nobody, the operator included, sets a password for somebody else. Whoever forgot theirs gets a link to set a new one: the operator sends it (Settings, Accounts), or, where a mail server and the public address are set, the person asks for it on the sign-in page. The link works once and for 24 hours.
  10. Passkeys work under the public https address, or on localhost.

Optionally keep the operator's settings at home: NEXDIARY_OPERATOR_NETWORKS: "192.168.0.0/16" refuses them from anywhere else (behind a proxy only together with NEXDIARY_TRUSTED_PROXIES).

⁠Sign-in through a provider

Settings, Sign-in has three cards: password sign-in, the public address and the second factor; the list of sign-in providers; and authentik in one step. Any provider that speaks OpenID Connect can go in the list (authentik, Microsoft Entra ID, Keycloak, Authelia, Pocket ID), each gets its own button on the sign-in page and its own redirect address, https://<public address>/api/oidc/<short name>/callback. The provider of nexdiary 0.6 and earlier became the entry oidc and keeps the address it had, /api/oidc/callback.

  • Somebody is found only by the link of their account to their identity at that provider, never by a mail address. An account links itself under My account, Security (with its password); new people come by invitation, or, where the operator switches on "New people get an account", as members.
  • "The provider checks the second factor itself" (per provider, on for a new one): then a sign-in through it asks for no code of nexdiary's own and sets none up. Off, whoever has a second factor here gives its code after the provider. An account that signs in through providers only is never made to set one up; an account with a password is, when it signs in with the password. The provider of 0.6 kept what 0.6 did: the code is asked unless its switch was on.
  • The operator can always sign in with the password, also when password sign-in is off for the others.
  • Each diary stays sealed with its own key; signing in through a provider opens the account it is linked to, like its password does, and nothing else.

Going back to 0.6: 0.6 does not open a database of schema 17. Restore the backup made before the update ("before schema 17") with 0.6; the next update moves the provider over again.

⁠Where things are stored

Everything lives in /data:

WhereWhat
nexdiary.dbThe SQLite database: accounts, days, notes, values, shares. What people write is sealed in it.
media/Photos, attachments and their small pictures, each sealed in its own file.
keys/master.keyThe master key, made at the first start (mode 0600). It wraps every person's data key.
secret.keyThe server's own secret (the client secrets of the sign-in providers, the mail password and the like).
backups/, logs/, locales/Backups, the log, extra languages as JSON files.

Mount /data from a local disk, never from an SMB or NFS share: SQLite's locking does not work reliably over network filesystems.

What people write is encrypted in the database: pages, notes, values, tags, photos, attachments and the Immich key. Each person has a data key of their own, wrapped with the master key. That keeps a copy of the database or of a backup unreadable on its own. The master key lies on the same machine, so this is no protection against somebody who owns the whole server; it is meant for the copies that leave it.

A backup cannot be read without the master key, and the master key is never part of a backup. Settings, Backups, Encryption downloads it (it asks for your password). Keep that file somewhere else than the backups, as carefully as a password. Lose it and every backup is only ciphertext; so is the live database if the key file is gone.

A backup is one ZIP file with the database and the media files, made while nexdiary runs. Moving to a new server: download a backup and the master key, set up nexdiary there with the key in keys/master.key, upload the backup under Settings, Backups, check it and restore it.

⁠Updating

With an image: docker compose pull && docker compose up -d. Built from source: pull the new code and run docker compose up -d --build. nexdiary adds what the database lacks at the start and makes a backup first; nothing needs doing by hand. The way back is under Settings, Backups.

⁠Forgot your password?

Ask the operator for a link (Settings, Accounts), or use "Forgot your password?" on the sign-in page where a mail server is set up. If you are the operator yourself, make the link on the server:

docker exec -it -u nexdiary nexdiary python -m app.reset_link <your name>

On Unraid, open the container's console instead and run gosu nexdiary python -m app.reset_link <your name>. Without a name it lists the accounts. It prints a link (or a path, when no public address is set: open it at the address you use for nexdiary). The link works once and for 24 hours and also ends the wait after too many attempts. Your second factor stays: after the new password, enter the code from your app or one of your recovery codes. Your diary stays as it is; it is not sealed with your password.

⁠Environment

VariableDefaultMeaning
NEXDIARY_DATA_DIR/dataDatabase, logs, backups, keys and the languages
NEXDIARY_MEDIA_DIR<data>/mediaThe photos
NEXDIARY_LOCALES_DIR<data>/localesExtra languages, one JSON file each
NEXDIARY_MASTER_KEY_FILE<data>/keys/master.keyWhere the master key lies; keep it outside the backups
NEXDIARY_SECRET_KEYmade on first startProtects server-side secrets; when set, it wins over secret.key
NEXDIARY_PUBLIC_URLfrom the requestThe address people use, for invitation links and the redirect address of the sign-in providers. The setting in the interface wins
NEXDIARY_TRUSTED_PROXIESnoneAddresses or networks of reverse proxies whose X-Forwarded-For and X-Forwarded-Proto (its rightmost value) are believed, comma separated
NEXDIARY_SETUP_TOKENmade at startThe code the first account needs
NEXDIARY_OPERATOR_NETWORKSnoneNetworks the operator's settings may be changed from, comma separated
NEXDIARY_SESSION_DAYS30A session of "stay signed in on this device" ends after this many days without use
NEXDIARY_COOKIE_SECUREautoon, off or auto (from the request, or X-Forwarded-Proto of a trusted proxy)
NEXDIARY_COOKIE_SUFFIXnoneAppended to the cookie names; keeps two instances on one host apart
NEXDIARY_LOG_LEVELstored settingquiet, normal, detailed or trace; overrides the setting
NEXDIARY_API_DOCSfalseServes /api/docs and /api/openapi.json
NEXDIARY_DECODE_SLOTS1How many pictures are unpacked at the same moment (each takes some 150 MB while open)
NEXDIARY_FFMPEG, NEXDIARY_FFPROBEfrom the PATHWhere ffmpeg and ffprobe are, for videos and sounds attached to a day (the image has both)
NEXDIARY_UPDATE_URLGitHubWhere the update check asks for the newest release
NEXDIARY_ARGON2_TIME, NEXDIARY_ARGON2_MEMORY_KIB, NEXDIARY_ARGON2_PARALLELISM3, 65536, 2Cost of the password hash; only the tests lower it
NEXDIARY_FRONTEND_DIST/app/staticWhere the built interface lies (set by the image)
NEXDIARY_DISABLE_BACKGROUNDfalseSwitches off the background jobs (reminders, backups, update check); for tests
NEXDIARY_PORT8000The port inside the container; only for host networking
PUID, PGID1000Owner of the files in the data directory
TZThe time zone of the container's log. People's own time zones come from their browsers

⁠AI

The AI is off until the operator chooses a service, for everybody (Settings, AI): none, a local model in your own network (Ollama or anything that speaks /v1/chat/completions), a service on the internet that speaks the same, or one that speaks the Messages API. Every person can switch it off for their account.

  • Nothing is sent without a press of a button ("Write it up with AI", "Ask me first", "Sum it up"), and nothing on a schedule.
  • What goes out when a day is written up, or when the AI asks first, are the notes of that one day, with their times and the questions they answer. No name, no date, no photos, no values.
  • What goes out when a week or a month is summed up are its pages: weekday, day of the month, title and text. No photos, values, tags or notes.
  • Before the button it says where the notes go: they stay at home, or the provider is named.
  • The AI orders and smooths, writes in the first person, short or long, and invents nothing. Its suggestion is only a suggestion in the editor; the notes are never changed.
  • With a template the headings and questions of the template go along as material, read from the database by their id; the AI writes under exactly those headings and leaves a section empty where the notes say nothing.
  • Writing up on its own is a second, deliberate step: the operator opens it (Settings, AI, off from the start), and each person switches it on for themselves (My account, AI, off from the start, with a confirmation that says where the notes go). Then, each morning at the chosen time, yesterday's notes become a draft that waits for you: it is no page, in no streak and no statistics and cannot be shared until you accept it. Each day is tried once.
  • A local model is asked not to think (reasoning_effort: "none"): a thinking model such as Qwen3 or DeepSeek-R1 would otherwise spend the room for its answer on its thoughts and give back nothing. A local server that does not know the field is asked once more without it.
  • A local service must lie in your own network and a service on the internet must be reached over https: an address that points elsewhere is refused, when it is saved and at every request. The API key is sealed and never shown again.

⁠Immich

Photos can come from your own Immich. The operator opens this first (Settings, Immich, closed from the start) and names the hosts that may be reached. Each person then connects their own: the address and an API key with the permissions asset.read, asset.view and asset.download (and, if you want to browse albums, album.read). "Today" suggests what was uploaded to Immich lately (it often receives a phone's photos hours late), and "All photos" opens your whole collection, newest first, with a date or month to jump to, your albums and a search. A photo is copied into nexdiary only when you take it, and belongs to the day it is taken for, whenever it was shot. The browser never talks to Immich: the small pictures come through nexdiary. Videos are left out.

⁠Push

Reminders and the notice of a new sign-in arrive by Web Push, to every device a person signs up (My account, Reminders). It needs https (or localhost). On an iPhone it works only for the app added to the home screen (Share, Add to Home Screen) and only from iOS 16.4. The server makes its own keys; the operator can add a contact and further push services. A push never carries anything written in the diary.

⁠For programs

Dashboards and scripts can read the version and the name of a token's account with an API token. Off until the operator switches it on; every account then makes its own tokens. Reading only. The routes are in docs/api.md⁠.

⁠Security in short

  • Passwords are hashed with Argon2id. Five failed sign-ins lock an account and an address for 15 minutes; with a second factor, the password alone opens nothing. A session ends after 30 days without use, or after 12 hours when "stay signed in" was not ticked, and every device can be signed out on its own.
  • Rights are checked on the server for every request: a person's days, notes, values and photos are theirs alone, and a day of somebody else opens only when it was shared with you. The operator manages accounts and never gets to entries.
  • Pages, notes, values, tags, photos and keys are encrypted with a key of each person.
  • Photos are drawn anew from their pixels (no metadata, no embedded code); pictures of more than 36 million pixels are refused before they are decoded; the storage per person is limited.
  • Every changing request needs a header a page on another site cannot send. Cookies are HttpOnly and SameSite; the Content Security Policy only allows the app's own files.
  • Addresses the server reaches out to (the AI, Immich, push services) are checked against the internet and the home network: resolved once, connected to exactly as checked, no redirect followed, never a metadata address.
  • The log never contains a word of a page or a note, passwords, keys or tokens.

How to report a problem: SECURITY.md⁠.


The full README is on GitHub: https://github.com/DerKezorm/nexdiary#readme⁠

Tag summary

Content type

Image

Digest

sha256:036ebed2c…

Size

252.2 MB

Last updated

about 21 hours ago

docker pull derkezorm/nexdiary