Getting started · Chapter 1

Setting up nexpaper

nexpaper runs as a single Docker container on your own server, a NAS for instance or a small computer at home. This chapter takes you as far as the first account. Putting nexpaper behind a reverse proxy, the environment variables and how updates work are covered in full under Self-hosting.

What you need

• A machine with Docker and Docker Compose. The image is built for Intel and AMD processors (amd64) and for ARM (arm64).
• A folder on a local disk for the data. nexpaper's database is a SQLite file, and it cannot live on an SMB or NFS share, because its locks do not work reliably over a network drive. The documents themselves may sit on a share later.
• An authenticator app on your phone, for the second factor. Any app that shows six-digit codes is fine. If you would rather not use an app, you can add a passkey later.

Starting the server

1. Create the compose file

   In an empty folder, create a file called docker-compose.yml. For a start, this is all it needs. The longer version with every option explained is on the Self-hosting page.

   docker-compose.ymlCopy

   services:
     nexpaper:
       image: ghcr.io/derkezorm/nexpaper:latest
       container_name: nexpaper
       restart: unless-stopped
       ports:
         - "127.0.0.1:8560:8000"
       volumes:
         - ./data:/data
       environment:
         PUID: 1000
         PGID: 1000
         TZ: Europe/Berlin

2. Start the container

   In the folder of the file:

   ShellCopy

   docker compose up -d

3. Fetch the setup code

   When it starts, nexpaper writes a setup code to its log. A new one is made at every start until the first account exists. If you would rather choose the code yourself, set NEXPAPER_SETUP_TOKEN.

   ShellCopy

   docker logs nexpaper

4. Open nexpaper

   The file above opens port 8560 on the machine itself only. There you reach nexpaper at http://127.0.0.1:8560. To reach it from your home network, write 8560:8000 instead of 127.0.0.1:8560:8000, but only for a network you trust. Without https, passwords and codes otherwise cross the network unencrypted. For everyday use a reverse proxy with https belongs in front of it, if only because the camera in the browser and passkeys both insist on an https address.

Creating the first account

The first page is called “Set up nexpaper”. The account you create here runs the server. It invites the others and may change every setting. It does not look into the personal vaults of the others. The setup code makes sure that nobody who happens to reach a fresh instance first can take it over.

Set up nexpaper

1. Enter the code, a name and a password

   “Setup code” takes the code from the log. The “Name” is the one you sign in with: 2 to 64 characters made of letters without accents, digits, dot, hyphen or underscore. The “Password” has at least 12 characters. Then tap “Create account”.

2. Set up the second factor

   Right after that comes “Set up your second factor”. It is compulsory out of the box for every account that signs in with a password. Scan the QR code with your authenticator app, or type in the key under it, enter the six digits the app shows under “Code from the app” and press “Turn on”.

3. Keep the recovery codes

   Now nexpaper shows eight recovery codes, this once and never again. Each one signs you in once when your phone is not at hand. Take them with you with “Copy” or “Save as file”. Keep them apart from the phone, then tap “I have them, go on”.

After that you are signed in. On a computer you see the archive, still empty; on a phone you see the quick upload. A passkey, which means signing in with a fingerprint, your face or the PIN of the device, you add later under “My account”, tab “Security”. It counts as two factors by itself. Passkeys need an address with https, and for that the operator has to enter the public address first (see below). Only on localhost do they work without.

What is worth doing next

• Enter the public address. Under “Settings”, tab “Sign-in”, you find the field “Public address”. Invitations, Web Push and passkeys need it, and so does a sign-in provider. Enter the address you reach nexpaper under, the one with https.
• Know the backup. Out of the box nexpaper makes a backup every night and keeps seven of them, in the data folder on the same server. A backup holds the accounts, the settings, the filing of the documents and the server key, but not the documents themselves. Those are plain files in the folder dokumente and belong in the backup your server makes anyway. More in the chapter Running it.
• Look before it goes on the internet. nexpaper is happiest inside your own network, reached by VPN when you are away. If you open it up anyway, “Settings”, tab “Sign-in”, has the card “Ready for the internet?”, which checks eight points by itself. More under Security.
• Invite the others. How that works is in the next chapter, Inviting people and sharing vaults.