Share notes with your team

The store keeps notes on your server, so everyone who opens the page sees the same notes, as they are written. It is two small files that need only Python, or one Docker container. Plan on ten minutes.

Before you start#

You need:

• A server that can run Python 3.8 or newer, or Docker. The same machine as your site is fine.
• Access to your web server's settings (nginx, Caddy, Apache or similar), to put the store at a path on your site.

1Start the store

Pick one.

With Python, from the unzipped download:

NOTES_DATA=/var/lib/notefix NOTES_BOARDS=staging python3 server/server.py

With Docker:

docker build -t notefix-store server/
docker run -d --name notefix --restart unless-stopped \
  -p 127.0.0.1:8097:8097 \
  -e NOTES_BOARDS=staging \
  -v notefix-data:/data \
  notefix-store

Either way it prints a line like notefix store on :8097 and is now listening on port 8097, on this machine only.

• NOTES_DATA is the folder for the database, notefix.db. This folder is your notes. Back it up (below).
• NOTES_BOARDS names your boards. More on those below.

2Put it at a path on your site

Browsers only let the page talk to its own site, so the store has to appear at a path on the same address, for example https://staging.acme.com/notefix-api/. Add this to your web server:

nginx

location /notefix-api/ {
    proxy_pass http://127.0.0.1:8097/;
    proxy_set_header Host $host;
}

Caddy

handle_path /notefix-api/* {
    reverse_proxy 127.0.0.1:8097
}

Apache

ProxyPass        /notefix-api/ http://127.0.0.1:8097/
ProxyPassReverse /notefix-api/ http://127.0.0.1:8097/

Keep the trailing slashes exactly as shown. Then check it: opening https://your-site.com/notefix-api/health should show {"ok": true, ...}.

3Point the tag at it

Add data-api to the line on your page:

<script src="/notefix/notefix-embed.js"
        data-project="Acme staging"
        data-api="/notefix-api"
        data-board="staging"></script>

4Check it with two browsers

Open the page in two different browsers, or one normal window and one private window. Leave a note in one. Within ten seconds it appears in the other.

That's it. Your team now shares notes.

Boards#

A board is one set of notes. Use one per site or project under review, so a checkout redesign and the marketing site do not share a list.

• The store makes the boards named in NOTES_BOARDS when it starts: NOTES_BOARDS=staging,checkout.
• The tag chooses one with data-board. Without it, each page uses a board named after its path: /checkout writes to checkout, /pricing/index.html to pricing-index-html. That name must be in NOTES_BOARDS, or the store refuses it.
• Removing a name from NOTES_BOARDS never deletes the board or its notes.

Most teams set data-board once in their layout, so every page of the site shares one board.

Keep it running#

With Docker, --restart unless-stopped already does this. With Python, run it as a service. On Linux with systemd:

# /etc/systemd/system/notefix.service
[Unit]
Description=Notefix store
After=network.target

[Service]
User=notefix
Environment=NOTES_DATA=/var/lib/notefix
Environment=NOTES_BOARDS=staging
ExecStart=/usr/bin/python3 /opt/notefix/server/server.py
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now notefix

Back it up#

Take a backup while the store is running:

# Python
NOTES_DATA=/var/lib/notefix python3 server/server.py backup /backups/notefix-$(date +%F).db

# Docker
docker exec notefix python3 server.py backup /data/backup-$(date +%F).db

This makes one complete, consistent file. Run it every night from cron and keep a few days of copies.

To restore: stop the store, put the backup in NOTES_DATA as notefix.db (removing any notefix.db-wal and notefix.db-shm beside it), and start the store.

Upgrading#

1. Take a backup.
2. Replace the notefix/ folder on your site and the server/ folder on your server (or rebuild the Docker image).
3. Restart the store.

The store updates its database by itself when it starts. It will not start on a database written by a newer version, so an accidental downgrade cannot damage your notes.

Coming from a version that kept notes in JSON files? Nothing to do: the first start imports every board, says so in its log, and leaves the old files where they were. Once you have checked your notes, you can delete them.

Next#

• Connect GitHub, Jira or Trello
• Tell Slack or email
• Security and privacy