Installation

Install from PyPI

Note

The recommended Python versions are 3.10 or 3.11. Some distributions may require additional steps to install Python 3.10/3.11. For example, on Ubuntu you can use the deadsnakes PPA:

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.11 python3.11-dev python3.11-venv

On Red Hat/CentOS/Alma/Rocky Linux, you can install Python 3.11 from AppStream or via an additional repo (EPEL / IUS). For example (RHEL 8+ / CentOS 8+ / Alma 8+ / Rocky 8+):

sudo dnf module reset python38
sudo dnf module enable python311 (or python3.12 if available)
sudo dnf install python3.11 python3.11-devel
# or use the "IUS" repo if needed

  1. Install dependencies:

    Required packages on Ubuntu 22.04+ (example for Python 3.10/3.11):

    sudo apt-get install \
    python3-virtualenv \
    python3.10 python3.10-dev \
    gcc libffi-dev libkrb5-dev libssl-dev \
    libyaml-dev libsasl2-dev libldap2-dev \
    default-libmysqlclient-dev sshpass git

    If you’re installing Python 3.11 instead of 3.10, adjust the packages accordingly:

    # Example
sudo apt-get install python3.11 python3.11-dev ...

    Required packages on Red Hat/Alma/Rocky 8+ (using Python 3.10/3.11 from module streams or a third-party repo):

    sudo dnf install epel-release
sudo dnf install python3.11 python3.11-devel python3-virtualenv \
    gcc openssl-devel libyaml krb5-devel krb5-libs \
    openldap-devel mysql-devel git sshpass

    Note

    If your OS is not listed, adapt the package list as needed. Polemarch itself does not require system-wide pinned package versions.

  2. Install MySQL server (if you plan to use MySQL):

    For Debian/Ubuntu:

    sudo apt-get install default-mysql-server

    Warning

    Do not use MySQL version older than 8.0.

  3. Create a database in MySQL with these commands (run on the DB host):

    sudo -H mysql <<QUERY_INPUT
# uncomment this line on old MariaDB/MySQL versions
# SET @@global.innodb_large_prefix = 1;
create user db_user identified by 'db_password';
create database db_name default CHARACTER set utf8 default COLLATE utf8_general_ci;
grant all on db_name.* to 'db_user';
QUERY_INPUT

    Note

    Adjust if connecting to a remote MySQL server.

  4. (Optional) If you use MySQL with a non-UTC timezone, import time zone info:

    mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo -H mysql mysql

  5. Create a dedicated system user for Polemarch:

    sudo useradd --user-group --create-home --shell /bin/bash polemarch

    Hint

    You can add this user to sudoers for easier administration.

  6. Create a virtualenv and activate it:

    # Adapt the python path to your installed version:
# For example, if you installed Python 3.11 in /usr/bin/python3.11:
virtualenv --python=python3.11 /opt/polemarch

# Create separated venv for ansible.
virtualenv --python=python3.11 /opt/polemarch/ansible

# Make required directories
sudo mkdir -p /etc/polemarch
sudo chown -R polemarch:polemarch /opt/polemarch /etc/polemarch
sudo -u polemarch -i
source /opt/polemarch/bin/activate

    Note

    If you have multiple Python versions, use 3.10 or newer. Adjust paths if you installed Python differently.

  7. Install Polemarch:

    # Here is example for mysql support.
# Use extra 'postgresql' instead of 'mysql' when install it on PG.
pip install -U polemarch[mysql]

# Install polemarch-ansible (here is example for ansible 2.5-2.9 support.
/opt/polemarch/ansible/bin/pip install 'polemarch-ansible~=2.2.0'
# or install latest ansible-core
/opt/polemarch/ansible/bin/pip install 'polemarch-ansible~=3.0.1' 'ansible-core~=2.18.1'

  8. Edit the config file:

    1. Create directories for logs and pids:

      mkdir /opt/polemarch/logs /opt/polemarch/pid

    2. Open /etc/polemarch/settings.ini (create it if it does not exist). Polemarch reads configs from /etc/polemarch/.

    3. Setup path for ansible module. You can wrap it to any script and realize any additional functionality (resource isolation, for example).

      [main]
executor_path = /opt/polemarch/ansible/bin/python -m pm_ansible

    4. MySQL settings example in settings.ini:

      [database]
engine = django.db.backends.mysql
name = db_name
user = db_user
password = db_password

[database.options]
connect_timeout = 20
init_command = SET sql_mode='STRICT_TRANS_TABLES', default_storage_engine=INNODB, NAMES 'utf8', CHARACTER SET 'utf8', SESSION collation_connection = 'utf8_unicode_ci'

      Note

      Add host and port if the DB is remote.

      Warning

      If you use MariaDB, add:

      [databases]
databases_without_cte_support = default

      Because MariaDB’s recursive CTE support differs from MySQL’s.

    5. (Optional) For better performance, configure Redis for caching and locks:

      [cache]
backend = django.core.cache.backends.redis.RedisCache
location = redis://127.0.0.1:6379/1

[locks]
backend = django.core.cache.backends.redis.RedisCache
location = redis://127.0.0.1:6379/2

    6. (Optional) For Celery/RPC, Redis or RabbitMQ is recommended:

      [rpc]
connection = redis://127.0.0.1:6379/3
heartbeat = 5
concurrency = 8
enable_worker = true

      Hint

      For large networks, RabbitMQ may be preferable.

    7. Configure uvicorn (HTTPS optional). For an HTTPS setup, provide keyfile/certfile:

      [uvicorn]
# Uncomment this for HTTPS support or use any proxy
# ssl_keyfile = /etc/polemarch/polemarch.key
# ssl_certfile = /etc/polemarch/polemarch.crt
# Setup here additional settings, like workers
# workers = 4

[web]
# default is
addrport = 0.0.0.0:8080

    8. If the server is not behind HTTPS or any TLS-terminating proxy, you need to allow insecure OAuth login:

      [oauth]
server_allow_insecure = true

      Note

      Alternatively, place Polemarch behind a TLS-terminating proxy such as Nginx, Traefik, or HAProxy and remove server_allow_insecure = true.

  9. Make migrations:

    polemarchctl migrate

    Note

    On the first run, the default superuser admin is created with the same password. Change it immediately after first login.

Configure systemd for Polemarch

Since polemarchctl webserver no longer daemonizes by default, it will keep the console busy. We recommend using systemd for management (start/stop/restart) of the service.

  1. Create a systemd unit file, for example: /etc/systemd/system/polemarch.service:

    [Unit]
Description=Polemarch Service
After=network.target

[Service]
Type=simple
User=polemarch
Group=polemarch
WorkingDirectory=/opt/polemarch
ExecStart=/opt/polemarch/bin/polemarchctl webserver
# If you want to store logs in a file, you can redirect:
# ExecStart=/opt/polemarch/bin/polemarchctl webserver >> /opt/polemarch/logs/polemarch_web.log 2>&1

Restart=on-failure

[Install]
WantedBy=multi-user.target

  2. Enable and start the service:

    sudo systemctl daemon-reload
sudo systemctl enable polemarch
sudo systemctl start polemarch

  3. Now Polemarch runs in the background. Manage it via standard systemd commands:

    sudo systemctl stop polemarch
sudo systemctl restart polemarch
sudo systemctl status polemarch

Note

Remove or ignore any references to the old uwsgi sections or the old polemarchctl webserver reload=/opt/polemarch/pid/polemarch.pid approach. All process management (start/stop/restart) is now delegated to systemd.

Install from docker

Run image

For run Polemarch docker image use command:

docker run -d --name polemarch --restart always -v /opt/polemarch/projects:/projects -v /opt/polemarch/hooks:/hooks -p 8080:8080 vstconsulting/polemarch

Using this command download official docker image and run it with default settings. Dont use default SQLite installation with filecache in production.

Ensure, that /opt/polemarch/projects and /opt/polemarch/hooks has uid/gid 1000/1000 as owner. Polemarch will be run with web interface on port 8080

Settings

Main section

  • DEBUG - status of debug mode. Default value: false.

  • DJANGO_LOG_LEVEL - log level. Default value: WARNING.

  • TIMEZONE - timezone. Default value: UTC.

Database section

Setup database connection via django-environ: environ.Env.db_url.

For example for mysql, DATABASE_URL = 'mysql://user:password@host:port/dbname'. Read more about django-environ in the official django-environ documentation.

Cache

For cache environment variables you can also use django-environ - environ.Env.cache_url. For example for redis, CACHE_URL = redis://host:port/dbname.

RPC section

  • POLEMARCH_RPC_ENGINE - connection to rpc service. If not set used as tmp-dir.

  • POLEMARCH_RPC_RESULT_BACKEND - connection to rpc results service. Default as engine.

  • POLEMARCH_RPC_HEARTBEAT - Timeout for RPC. Default value: 5.

  • POLEMARCH_RPC_CONCURRENCY - Number of concurrently tasks. Default value: 4.

Web section

  • POLEMARCH_WEB_REST_PAGE_LIMIT - Limit elements in answer, when send REST request. Default value: 1000.

Other settings

If you set SECRET_KEY, value of SECRET_KEY variable would be written to secret

Examples

Run latest version of Polemarch in docker and connect to MySQL on server, using django-environ:

docker run -d --name polemarch --restart always -v /opt/polemarch/projects:/projects -v /opt/polemarch/hooks:/hooks --env DATABASE_URL=mysql://polemarch:polemarch@polemarch_db:3306/polemarch -p 8080:8080 vstconsulting/polemarch

Run Polemarch with Memcache and RabbitMQ and SQLite3. Polemarch log-level=INFO, secret-key=mysecretkey

docker run -d --name polemarch --restart always -v /opt/polemarch/projects:/projects -v /opt/polemarch/hooks:/hooks --env POLEMARCH_RPC_ENGINE=amqp://polemarch:polemarch@rabbitmq-server:5672/polemarch --env CACHE_URL=memcache://memcached-server:11211/ --env POLEMARCH_LOG_LEVEL=INFO --env SECRET_KEY=mysecretkey -p 8080:8080 vstconsulting/polemarch

Also you can use .env file with all variable you want use on run docker:

docker run -d --name polemarch --restart always -v /opt/polemarch/projects:/projects -v /opt/polemarch/hooks:/hooks --env-file /path/to/file -p 8080:8080 vstconsulting/polemarch

Run from the sources with docker-compose (PoleMarch+MySQL+Redis):

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
docker-compose up -d --build

Quickstart

After you install Polemarch by instructions above you can use it without any further configuration. Interface is pretty intuitive and common for any web application. Read more in GUI workflow.

Default installation is suitable for most simple and common cases, but Polemarch is highly configurable system. If you need something more advanced (scalability, dedicated DB, custom cache, logging or directories) you can always configure Polemarch like it is said in Configuration manual.

Backup

Regular uploading of backups is a guarantee of the reliability of the application. We recommend use SQL backup or copy database.

There are examples of SQL backup for MySQL and PostgreSQL below.

Making backup in MySQL:

shell> mysqldump dbname > dump.sql

Here dbname is the name of your database, dump.sql is the file, where all SQL backup statements will be saved.

Uploading of backup in MySQL:

shell> mysqladmin create dbname
shell> mysql dbname < dump.sql

Making backup in PostgreSQL:

pg_dump dbname > dump.sql

Uploading of backup in PostgreSQL:

createdb dbname
psql dbname < dump.sql

Update

Before updating of package of any type it is strongly recommended to stop all services and create backup for safety.

Update from any old version

  1. Firstly, we strongly recommend you to create a database backup and to stop all Polemarch services for safety.

  2. Secondly, if you are updating from 0.x.y to 1.x.y, you need to update you current 0.x.y version to 1.0.0 version.

  3. Then update to the latest version. If you don’t know how to do it, look “Install from PyPI”.

Migrate

Migrations are Django’s way of propagating changes you make to your models (adding a field, deleting a model, etc.) into your database schema. They’re designed to be mostly automatic, but you need to know when to make migrations, when to run them, and the common problems you might run into.

To run a migrate command you should run follow code:

polemarchctl migrate

Create superuser

A superuser is the user, who has all permissions.

To create a superuser account use the follow command:

polemarchctl createsuperuser

This command prompts for all required user’s options.

Change password

To change password use the follow command:

polemarchctl changepassword [<username>]

It prompts you to enter a new password twice for the given user. If the entries are identical, this immediately becomes the new password. If you do not supply a user, the command will attempt to change the password of user whose username matches the current user.