Run your own Notefix server

Notefix Self-hosted is the same server as Notefix Cloud, on your own machine: accounts, projects, the dashboard, connections and email. Your notes never leave your server. Plan on twenty minutes, most of it email and your web server's settings.

Before you start#

You need:

• A server with Docker, or Python 3.8 or newer.
• An address for it with HTTPS, such as https://notes.acme.com. A subdomain of its own is simplest.
• A mail server Notefix can send through (SMTP). Sign-in is by emailed link, so without one nobody can sign in, except from the server itself.

1Start it

With Docker:

docker build -t notefix server/
docker run -d --name notefix --restart unless-stopped \
  -p 127.0.0.1:8097:8097 \
  -v notefix-data:/data \
  --env-file /etc/notefix.env \
  notefix

With Python, from the unzipped download in /opt/notefix, as a systemd service that reads the same file:

# /etc/systemd/system/notefix.service
[Service]
EnvironmentFile=/etc/notefix.env
Environment=NOTES_DATA=/var/lib/notefix
ExecStart=/usr/bin/python3 /opt/notefix/server/server.py
Restart=always
User=notefix

[Install]
WantedBy=multi-user.target

/etc/notefix.env holds the settings below, one NAME=value per line. Keep it readable only by root: it has your mail password in it.

NOTEFIX_PUBLIC_URL=https://notes.acme.com
NOTEFIX_EMAIL_FROM=Notefix <[email protected]>
NOTEFIX_SMTP_HOST=smtp.acme.com
[email protected]
NOTEFIX_SMTP_PASSWORD=...

2Put HTTPS in front

Point your web server at port 8097, on the whole address:

server {
    server_name notes.acme.com;
    location / {
        proxy_pass http://127.0.0.1:8097;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Behind a proxy like this, also set NOTEFIX_TRUST_PROXY=1, so sign-in limits count each visitor, not the proxy.

3Sign in and make a project

Open https://notes.acme.com/app, sign in with your email, and follow Get started with Notefix Cloud from step 2. Your tag loads from your own server:

<script src="https://notes.acme.com/v1/notefix-embed.js"
        data-project="acme-website-k7f2q9" defer></script>

One-click connecting#

Out of the box, owners connect GitHub, Jira, Trello and Slack by pasting a key, with a guide on each step. Register an app with a tool, give its details to the server, and that tool gets a Continue with button instead. Each is optional and separate.

Every callback address is your public address plus /app/oauth/ and the tool: https://notes.acme.com/app/oauth/github, and so on.

GitHub#

GitHub, Settings, Developer settings, GitHub Apps, New GitHub App:

• Callback URL: https://notes.acme.com/app/oauth/github
• Tick Request user authorization (OAuth) during installation.
• Webhook: untick Active.
• Repository permissions: Issues, Read and write. Metadata turns Read-only by itself.
• Account permissions: Email addresses, Read-only. This is for Sign in with GitHub; leave it at No access if you do not want that.
• Where can this GitHub App be installed: only on this account, unless other organisations will use your server.

Create it, then Generate a new client secret and Generate a private key.

One address per app. After somebody installs the app, GitHub sends them to the first callback URL in the list, whichever server they started from. Give each address its own app: one for notes.acme.com, another for a staging server. (To reorder the list anyway: delete the others, save, then add them back. Swapping two addresses in place is refused as already been taken.)

Check the app once the settings are in place. This asks GitHub about the app with its own key, and prints its name and permissions, which should include issues: write:

python3 -c "import json,urllib.request,oauth; print(json.load(urllib.request.urlopen(urllib.request.Request('https://api.github.com/app', headers={'Authorization': 'Bearer ' + oauth.app_jwt(), 'User-Agent': 'notefix'}))))"

Run it from the server's folder, with the settings loaded.

NOTEFIX_GITHUB_APP_ID=123456
NOTEFIX_GITHUB_APP_SLUG=acme-notefix          # from github.com/apps/acme-notefix
NOTEFIX_GITHUB_CLIENT_ID=Iv23li...
NOTEFIX_GITHUB_CLIENT_SECRET=...
NOTEFIX_GITHUB_APP_KEY=/data/github-app.pem   # the private key file

Jira#

developer.atlassian.com/console/myapps, Create, OAuth 2.0 integration:

• Permissions, Jira API: add read:jira-work, write:jira-work and read:jira-user, and, for sprints, read:project:jira, read:board-scope:jira-software, read:sprint:jira-software and write:sprint:jira-software.
• Authorization, OAuth 2.0 (3LO): callback https://notes.acme.com/app/oauth/jira.

NOTEFIX_ATLASSIAN_CLIENT_ID=...
NOTEFIX_ATLASSIAN_CLIENT_SECRET=...

Trello#

trello.com/power-ups/admin, New. Under API key, generate one, and add https://notes.acme.com to Allowed origins.

NOTEFIX_TRELLO_KEY=...

Slack#

api.slack.com/apps, Create New App, From scratch:

• OAuth & Permissions: redirect URL https://notes.acme.com/app/oauth/slack, and the scope incoming-webhook.
• Basic Information has the client ID and secret.

NOTEFIX_SLACK_CLIENT_ID=...
NOTEFIX_SLACK_CLIENT_SECRET=...

Sign in with Google#

Out of the box, people sign in with an emailed link. Register a Google client and the sign-in page, and the window your sites open, also show Continue with Google. The emailed link stays.

In console.cloud.google.com, in a project of its own:

• Google Auth Platform, then Get started: your app's name, and External.
• Branding: your public address as the home page, and its domain under Authorised domains.
• Data access: only openid, .../auth/userinfo.email and .../auth/userinfo.profile. They need no review from Google.
• Clients, Create client, Web application, with the redirect URI https://notes.acme.com/app/oauth/google.
• Audience: while you try it, only the test users you list can sign in. Press Publish app when everyone should.

NOTEFIX_GOOGLE_CLIENT_ID=....apps.googleusercontent.com
NOTEFIX_GOOGLE_CLIENT_SECRET=...

Google tells the server the person's name and email address, and signs in the account for that address, the same one an emailed link would. An address Google has not confirmed is not accepted.

Sign in with GitHub comes with the GitHub App: once it is set up, with Email addresses Read-only, Continue with GitHub appears beside Google. It signs in the account for the GitHub account's confirmed primary address. GitHub asks each person to authorise the app once, and after that sends them straight back.

Restart the server after changing any of these.

Settings#

Everything is optional except the address and mail.