¶ Getting Started with Polynom™ Community Server for Linux:
Polynom Community Server is a single, statically linked binary developed for rapid deployment with modest resources. The binary will initialize all files, folders, and the database on the first run in the same folder as the binary. There are two methods of deploying a Polynom Server: manually or using Docker. With both methods, it is best to prepare the Server-Admin's Graphatar in advance, which we will cover in the instructions below.
¶ Minimum Requirements
This getting started guide assumes:
- you intend to host Polynom on a linux server;
- you have basic understanding of using linux from the command line;
- you have access to your server from a windows or linux machine (remote commands can vary between the two, as outlined below);
- a basic understanding of firewalls;
- the ability to port forward through your home router if hosting from home.
Minimum requirements needed to install and run the Polynom Server are:
- A physical or virtual machine running a fully updated amd64 Debian 12+;
- 1 vCPU or physical CPU core; and
- 1 GB of RAM
¶ Prepare Your Server-Admin Graphatar™
Note:Every server needs at least one Server-Admin to oversee all matters. The Server-Admin has, by default, all roles on the server and should not be confused with the slightly less powerful Admin Role baked into the server.
- Install the Polynom Client to your desktop or android device;
- If you don't have it already, create the Graphatar that will be assigned as the Server-Admin;
- Copy the hash of the Server-Admin's Graphatar into a file called admin.txt or similar;
- While multiple Server-Admin addresses (one per line) are supported, it is not recommended;
- Set the admin.txt file(s) aside for server initialization.
VERY IMPORTANT: You must know and trust any person given these rights on your server, as they can delete content and blacklist/whitelist users.
¶ Initialize the Polynom Server
This section assumes that you have a local or remote server already set up, and that you have ssh access and sudo privileges for an ordinary user.
The Polynom Server binary will create all the files and subfolders in its current working directory, so you are free to choose where it will live. Purists will want to adhere to the Linux Filesystem Hierachy Standard (FHS) and install the binary in /opt/polynom/ or /opt/codesiren/polynom/ but this is not strictly necessary. A folder in the host user's home folder will suffice. Wherever you choose, make a Polynom folder wherever you choose and copy the polynom_server binary into it. Make it executable.
¶ Download the Polynom Server tar.gz
From the server's command prompt:
$ wget https://polynom.app/releases/polynom_linux_server.tar.gz
$ tar -xvf polynom_linux_server.tar.gz
$ mkdir ~/polynom
$ cp polynom_server ~/polynom/polynom_server # or copy from wherever it happens to be
$ chmod +x ~/polynom/polynom_server
¶ Make Sure the Port Is Open on the Server
We need both UDP & TCP open on the server. These commands assume you are using UFW Firewall. Adapt as necessary if you are using iptables, etc. You may also need to port forward from your router.
$ sudo ufw allow 1337/tcp
$ sudo ufw allow 1337/udp
Important If you are hosting from your home or business, you will also need to port forward from your router. Follow your router's instruction manual for forwarding the port you defined for polynom to the local IP address of your server.
¶ Server First Run
When installing the server manually, you have two options for the first server run. If installing the server using Docker, the server is started for you in normal mode, so the second method applies:
- Start the server in admin mode (-a), automatically turning any client that links to the server into a Server-Admin. Stop the server and restart in normal mode, or
- Start the server in normal mode. Stop the server, add the admin.txt file created in the previous section to the
adminfolder, then restart in normal mode.
In either case, after the second restart, you can enter u at the command prompt to be shown a list of users - which should, at this point, only include Server-Admin(s).
Polynom Server does not run as a daemon. In order to maintain and then recover the active console after leaving the host, it is best to start the binary using either tmux or screen.
This is an external link to a Tmux Cheatsheet, use at your own risk.
Here is how I do it with tmux if I already have the admin.txt ready to go. Adapt as you see fit:
$ sudo apt install tmux
$ cd polynom (or your path)
$ tmux new -s poly-session
$ ./polynom_server
The server should now start.
Type ? to see the server options.
Type x to exit the server so we can add your Server-Admin user (admin.txt).
Keep this session alive as we'll come back to it in a moment.
Copy the admin.txt file you made earlier to the server and into the ~/polynom/admin/ folder that Polynom created. In this tutorial, we will assume you will use the Putty (pscp) utility. Replace ${USER} with your user name on the remote host. Linux users can use scp.
From your local Windows/Linux command prompt, change directory cd to the location of your admin.txt file and then secure copy the admin.txt to your remote server.
Windows:
$ cd C:\Users\${USER}\Documents\ (or similar path).
$ pscp admin.txt ${USER}@<Server_IPAddress>:/home/${USER}/polynom/admin/
Linux:
$ cd /home/${USER}/Documents (or similar path).
$ scp admin.txt ${USER}@<Server_IPAddress>:/home/${USER}/polynom/admin/
Return to your ssh tmux session and restart Polynom:
$ ./polynom_server
Add your new server from the Polynom desktop app and ensure you can access it.
You will know you have been successful with server setup if your desktop app can connect. In your tmux session, type a to list all the users on the server. You should see only those users who were in the admin.txt file. If you started with -a, ensure that no strangers joined your server as Server-Admins while you were setting up.
You can now detach from your tmux session. NOTE: YOU MUST ALWAYS DETACH FROM TMUX. If you leave without detaching from the tmux session, you will crash your server. Always detach with Ctrl-b d before ending your ssh session.
To reclaim your tmux session, ssh into the remote server, then use $tmux attach
Your new server has been configured in Private Mode by default to prevent random users from joining while you were setting up. The Server-Admin can now configure this setting (and others) within the desktop application.
If you keep your server Private, you must add new user's public keys to the whitelist before their client can connect.
Have fun with the world's first PQC collaboration app!
This Dockerfile is an example only and is provided here 'as is'. It is known to work but has not been battle-tested for production security. Use at your own risk.
FROM debian:bookworm-slim
RUN apt-get -y update &&\
useradd --shell /bin/bash -u 1000 -o -c "" -p nom -m nom &&\
export HOME=/home/nom &&\
mkdir -p /home/nom/opt/polynom
WORKDIR /home/nom/opt/polynom
COPY polynom_server .
RUN chmod +x /home/nom/opt/polynom/polynom_server &&\
chown -R nom:nom /home/nom
USER nom
EXPOSE 1337/tcp
EXPOSE 1337/udp
ENTRYPOINT ["/home/nom/opt/polynom/polynom_server"] CMD [ "-p 1337"]
This yaml file is an example only and is provided here 'as is'. It is known to work but has not been battle-tested for production security. Use at your own risk.
version: '3.7'
services:
polynom:
image: caraka/polynom_pro:0.15.14
container_name: polynom
hostname: polynom
user: 1000:1000
stdin_open: true
tty: true
ports:
- "1337:1337/tcp"
- "1337:1337/udp"
volumes:
- /home/$${USER}/opt/polynom:/home/nom/opt/polynom
command:
- '-k $$(cat /run/secrets/polynom_sqlite_key)'
#environment: # for future use
#POLYNOM_SQLITE_KEY_FILE: /run/secrets/polynom_sqlite_key
secrets:
- polynom_sqlite_key
restart: unless-stopped
secrets:
polynom_sqlite_key:
file: /home/$${USER}/opt/polynom/polynom_sqlite_key
Please note that mounting a volume this way will overwrite the server binary in the container with whatever is in this path on the host. The key takeaway from this example is the stdin_open and tty items, which ensure that you can use $docker attach <container_name> to reach the correct/active console in your container. You would type Ctrl-P followed by Ctrl-Q to detach from the container. This is more convenient than using tmux or screen.
The polynom_sqlite_key file which contains the encryption key for the server db needs to be owned soley by root to protect your secret:
sudo chown root:root polynom_sqlite_key
sudo chmod 600 polynom_sqlite_key
This docker-compose file will encrypt a new database on first run, and allow it to be decrypted/used in subsequent runs. It will NOT encrypt a pre-existing database.
¶ Server Administration
¶ Startup Options
If you have many users connected to your server, consider increasing your soft open file limit to an acceptable number before you start Polynom. For example, on Debian the default soft open file limit is 1,024. You might consider increasing iit to 4,096, 8,192, or even higher depending on your needs.
To temporarily increase the ulimit, use: #ulimit -Sn 65536 then start Polynom.
For a permanent change that survives reboots, edit:
#nano /etc/security/limits.conf
insert * soft nofile 65536 save, then reboot.
You can check your work after reboot with #ulimit -Sn
Use these at startup if necessary:
-dTo disable the mobile push gateway. This does NOT daemonize/background the process!-t xxUse this to change the number of threads available to Polynom Server from the default (16).-p xxxxUse this option to change the port from the default (1337).
¶ Console Options
You can type h or ? + Enter at the prompt to see the options.
¶ Views:
¶ Functions:
gGenerate a new Polynom Server key;pPurge File Cache;rRestart;uUpdate;xExit.
¶ Adding/Removing Admins
If you add or remove an admin address file while Polynom Server is runningthis will be detected and take effect immediately.
¶ SQLite Server Encryption
This feature has just been released, but these notes are preliminary and incomplete.
-kcmd-line arg can take up to 2 arguments-k 12345indicates that my database is encrypted with a key derived from the passphrase "12345". Use this on first start (when there is no DB file already), or for an existing DB file that is already encrypted with this key-k old_pwd new_pwdis the syntax to use when updating encryption keys.-k "" 12345will go from an unencrypted DB file to one encrypted with a key derived from "12345" passphrase.-k 12345abcde will update the key to a new key derived from "abcde" as the passphrase.
-k ""does nothing and is the same as running without any -k option- Passphrases can be enclosed in quotes (and must be if there are any spaces, etc)
POLYNOM_SQLITE_KEYis an env variable that works the same as-k PWDThe env var is ONLY chcked if -k isn't on the cmd-line (mostly here for K8s future use)