Reference

Every setting in one place. The guides explain when you need each one.

The tag#

Attribute	Default
`data-project`	the page title	The name shown in Notefix
`data-api`	none	The store's path on your site. Without it, notes stay in each browser
`data-board`	the page's path	Which board the page's notes go on
`data-issues`	none	`queue` turns on Create an issue for a connector. Needs `data-api`
`data-docs`	docs.notefix.app	Where Settings sends people to set up a connection. `off` removes the links
`data-theme`	`dark`	`light` or `dark`
`data-rail`	tucked	`pinned` starts with the toolbar on screen
`data-mobile-breakpoint`	`560`	Below this width the toolbar and All notes move to the bottom, for a thumb
`data-phone`	on	`off` hides Notefix entirely below that width

window.NotefixConfig, set before the tag, can add functions: screen (the current screen's name), scroller (the element that scrolls) and createIssue (your own tracker).

Store#

python3 server/server.py                  # run it
python3 server/server.py backup <file>    # a consistent copy, while it runs

Setting	Default
`NOTES_DATA`	`/data`	Folder for the database
`NOTES_DB`	`NOTES_DATA/notefix.db`	The database file, if it should be elsewhere
`NOTES_PORT`	`8097`
`NOTES_BOARDS`	`staging`	Boards to make on start, separated by commas. Never removes one
`NOTES_CONNECTOR_SECRET`	none	Required by connectors to change tickets, and by the notifier to read email settings. Turns on email sign-up
`NOTES_ISSUE_HOSTS`	`github.com,trello.com,atlassian.net`	Sites a ticket link may point to
`NOTES_CLAIM_LEASE`	`600`	Seconds a connector may hold a note before another may try
`NOTES_SIGNUPS_PER_HOUR`	`30`	New email sign-ups a board accepts in an hour
`NOTES_ALLOW_ORIGIN`	none	For local development only

Connector#

python3 connectors/runner.py github     # or jira, trello

Setting	Default
`NOTEFIX_API`	`http://127.0.0.1:8097`	The store, as the connector reaches it
`NOTEFIX_BOARD`	`staging`	The board to work on
`NOTEFIX_SECRET`	none	The store's `NOTES_CONNECTOR_SECRET`
`NOTEFIX_SITE`	none	The site's address, for the link back from each ticket
`NOTEFIX_LINK`	`NOTEFIX_SITE{screen}?note={id}`	The link back, when your addresses are shaped differently
`NOTEFIX_POLL`	`15`	Seconds between looks for waiting notes
`NOTEFIX_CHECK`	`60`	Seconds between checks on filed tickets
`NOTEFIX_GIVE_UP`	`8`	Tries on one note before giving up
`NOTEFIX_ONCE`		`1` to run one pass and stop, for cron

GitHub
`GITHUB_TOKEN`	A fine-grained token with Issues: Read and write
`GITHUB_REPO`	`owner/name`
`GITHUB_LABELS`	Optional labels, separated by commas

Jira
`JIRA_SITE`	`https://yourteam.atlassian.net`
`JIRA_EMAIL`	The token owner's email
`JIRA_TOKEN`	An API token
`JIRA_PROJECT`	The project key, like `WEB`
`JIRA_ISSUE_TYPE`	Optional. Bug if the project has it, else Task
`JIRA_LABELS`	Optional extra labels. `notefix` is always added
`JIRA_SPRINT`	`active` to add issues to the current sprint

Trello
`TRELLO_KEY`	The API key
`TRELLO_TOKEN`	The token
`TRELLO_BOARD`	The board's name
`TRELLO_LIST`	Optional. Where new cards go. The first list by default
`TRELLO_DONE_LISTS`	Optional. Lists that mean finished. `Done` by default

Notifier#

python3 connectors/notify.py

Setting	Default
`NOTEFIX_API`	`http://127.0.0.1:8097`	The store
`NOTEFIX_BOARD`	`staging`	The board to watch
`NOTEFIX_SITE`	none	The site's address, for links to notes
`NOTEFIX_LINK`	`NOTEFIX_SITE{screen}?note={id}`	The link, when addresses are shaped differently
`NOTIFY_STATE`	`./notefix-notify-<board>.json`	Where it remembers what it announced
`NOTIFY_SETTLE`	`30`	Seconds a note must stay unchanged
`NOTIFY_BATCH`	`90`	Seconds to gather changes into one Slack message
`NOTEFIX_POLL`	`15`	Seconds between looks at the board
`NOTEFIX_DRY_RUN`		`1` to print messages instead of sending them
`NOTEFIX_ONCE`		`1` for one pass. For cron, also set `NOTIFY_SETTLE` and `NOTIFY_BATCH` to `0`
`NOTIFY_SLACK_WEBHOOK`	none	A Slack incoming webhook
`NOTIFY_SLACK_CHANNEL`	none	The channel's name, shown in Settings. Only a label
`NOTIFY_ALERTS`	`on`	`off` to never announce a broken connection
`NOTIFY_ALERT_AFTER`	`120`	Seconds a connection must stay broken before the team is told
`NOTIFY_ALERT_EMAIL`	none	Also email broken connections to this address. Needs the mail settings
`NOTIFY_EMAIL_FROM`	none	Required for email
`NOTIFY_SMTP_HOST`	none	Required for email
`NOTIFY_SMTP_PORT`	`587`, or `465` with `ssl`
`NOTIFY_SMTP_TLS`	`starttls`	`starttls`, `ssl`, or `none` for a local test server
`NOTIFY_SMTP_USER`, `NOTIFY_SMTP_PASSWORD`	none
`NOTIFY_EMAIL_PEOPLE`	none	A file of people to email
`NOTIFY_EMAIL_BATCH`	`600`	Seconds to gather changes into one email
`NOTIFY_DIGEST_HOUR`	`9`	Hour of the daily summary, in the server's time zone
`NOTEFIX_SECRET`	none	Required for email. The store's `NOTES_CONNECTOR_SECRET`
`NOTEFIX_PUBLIC_API`	none	Required for email. The store's `https://` address as browsers reach it

Store API#

For building your own connector. Paths are relative to the store, so through the proxy they start with your data-api path.

Request
`GET /health`	`{ok, boards}`
`GET /<board>`	The whole board: notes and deletions
`GET /<board>?rev=N`	`{changed: false}` if nothing changed since `rev` N
`POST /<board>`	Merges the notes and deletions sent, and returns the board
`GET /<board>/issues`	Every note waiting to be filed, in full
`POST /<board>/notes/<id>/claim`	Take a note before filing it. `409` if another connector has it, or if the note's `issue.to` names another tracker
`POST /<board>/notes/<id>/filed`	The ticket exists: `{by, ref, url, ext}`. The note stays open
`POST /<board>/notes/<id>/done`	The ticket was closed. The note is marked done
`POST /<board>/notes/<id>/reopen`	The ticket was reopened. The note opens again
`POST /<board>/connectors`	A connector says what it is and how it is doing: `{every, items: [{kind, role, target, ok, problem}]}`. `role` is `issues` or `messages`; `problem` is `key`, `missing`, `offline`, `setup` or `other`
`GET /<board>/connections`	What Settings shows: each connection with its `state` (`working`, `problem`, `stopped` or `paused`) and `url`
`POST /<board>/connections/<kind>/pause`	`{paused: true}` or `{paused: false}`, for the whole board. A paused tracker's claims are refused

With NOTES_CONNECTOR_SECRET set, the four notes/<id>/… requests and POST /<board>/connectors need the header Authorization: Bearer <secret>.

Merging: for each note, the copy with the newer updated time wins. A deletion is kept as deleted[id] = time, and removes any copy of the note not updated after it.