¶ 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, unless you use the optional environmental variable POLYNOM_SERVER_PATH. 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 directoryor in the directory specified in the POLYNOM_SERVER_PATH environmental variable, 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/1.2/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).
These are the server flags/switches for the as yet UNRELEASED v1.0 server:
Polynom Community Server Usage:
-a [ --admin ] Enable admin mode
-f [ --folder ] arg Folder path
-g [ --gateway ] arg Gateway endpoint (address:port)
-G [ --gateway_hash ] arg Gateway hash
-h [ --help ] Display this help message
-l [ --log ] Log to the screen
-p [ --port ] arg Port number (1 - 65535)
-t [ --threads ] arg Number of threads (2 - N)
-v [ --version ] Display the version number
Polynom Professional Server Usage:
-a [ --admin ] Enable admin mode
-f [ --folder ] arg Folder path
-g [ --gateway ] arg Optional Gateway endpoint (address:port)
-G [ --gateway_hash ] arg Gateway hash
-h [ --help ] Display this help message
-k [ --keys ] arg Database encryption key(s)
-l [ --log ] Log to the screen
-m [ --maria ] MariaDB database
-p [ --port ] arg Port number (1 - 65535)
-t [ --threads ] arg arg (Number of main threads (2 - N) # of gateway threads)
-v [ --version ] Display the version number
Using -g without an address:port turns on the default gateway, and is suitable for most users. Polynom Enterprise will have an optional gateway server for users to self-host.
By default, if you do not specify a gateway threadpool, it will be set at half of what you set for the main threadpool.
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 tmux, screen or docker attach if using docker.
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 set -x &&\
groupadd --gid 1000 nom &&\
useradd --gid nom --no-create-home --shell /bin/bash --uid 1000 nom
# Placeholder: Add the server path in the docker run or docker compose stage of the deployment
ENV POLYNOM_SERVER_PATH=
COPY polynom_server /usr/local/bin
RUN chmod +x /usr/local/bin/polynom_server &&\
chown nom:nom /usr/local/bin/polynom_server &&\
mkdir /data &&\
chown nom:nom /data
USER nom
EXPOSE 1337/tcp
EXPOSE 1337/udp
ENTRYPOINT ["polynom_server"]
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.
services:
polynom:
image: caraka/polynom_server:1.2.0
container_name: polynom
hostname: polynom
user: 1000:1000
stdin_open: true
tty: true
ports:
- "1340:1337/tcp"
- "1340:1337/udp"
environment:
- POLYNOM_SERVER_PATH=/data
volumes:
- <your/data/path>:/data
command:
# enables mobile (FCM) notifications:
- -g
# encrypts the db with the sqlite_key:
- '-k $$(cat /run/secrets/polynom_sqlite_key)'
secrets:
- polynom_sqlite_key
restart: unless-stopped
secrets:
polynom_sqlite_key:
file: ./polynom_sqlite_key
The key takeaways from this example are the POLYNOM_SERVER_PATH, the stdin_open and tty items.The server path tells docker where to store the polynom db and files. The last 2 items 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:
aAccess - lists the addresses of admins, blacklisted addresses, and whitelisted addresses;cConnections - lists devices recently connected;iProgram Info - prints the Polynom Server information;
¶ 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.