Server Deployment

This section describes how to deploy the Parsec Server on Linux.

Before you begin, take a look at the Application architecture section for an overview of software systems and interactions involved with the Parsec Server.

The steps and requirements described in this section may vary based on your specific needs. It is recommended to deploy and observe performance on a pilot project prior to using in production.

Note

Some setup and administrative operations must be performed with Parsec CLI on Linux. Please refer to the Install Parsec CLI on Linux section.

Deployment options

Parsec offers the following deployment options:

• Container-Based deployment

• Direct installation on Linux server

Prerequisites

The Parsec Server depends on the following components:

• A PostgreSQL database to store Parsec metadata.

• An S3-like object storage (e.g. OpenStack Swift or Amazon S3) to store encrypted data.

• An SMTP server to allow sending emails from the Parsec Server.

• A TSL/SSL server certificate for HTTPS communication with Parsec client applications.

Optionally, the following components can be used to support additional features:

• A Sentry Data Source Name (DSN) to support Parsec Server telemetry reports.

• A CryptPad server to support document editing from Parsec client applications.

• An OpenBAO server to support authentication with SSO.

Important

For security reasons, installation and configuration of these components are not covered in this guide. Please refer to their corresponding official documentation for instructions on how to do it.

This guide provides instructions for quickly settings up mock-ups or basic installs of those components. Keep in mind that these instructions are provided for convenience and should not be used in production.

Important

It is not recommended to deploy both Parsec Server and PostgreSQL database on a single system for production use, but it is a good option for testing purposes.

System Requirements

The following panel describes the minimum software and hardware requirements.

Minimum system requirements

• Hardware: 1 vCPU/core with 1GB RAM

• Database: PostgreSQL v16+, 20GB for metadata storage

• S3 Object Storage: 2TB for encrypted data storage (around x100 metadata size)

Preparation

TLS certificates

This section describe how to generate the required TLS certificates with a custom Certificate Authority (CA) created for this purpose.

Important

For a production environment, you should always use certificates issued from a trusted CA.

The setup-tls.sh script below will allow you to generate everything you need:

1. Generate the CA key & self-signed certificate (custom-ca.{key,crt}).

2. For parsec-s3 and parsec-server services:

   1. Generate the service key & Certificate Signing Request (CSR) parsec-{service}.{key,csr}.

   2. Generate the certificate using the CSR and the CA.

3. For parsec-server service:

   1. Change the key file group ID to 1234 (the GID used by the parsec-server container).

   2. Change the file mode to give read permission to the group 1234. This is required because Docker Compose does not allow to mount the file with the correct permissions in the container.

setup-tls.sh

# shellcheck disable=SC2148
function generate_cert_conf() {
    local name=$1
    local san=$2

    echo "Generating $name.crt.conf"

    cat << EOF > "$name".crt.conf
[req]
distinguished_name = req_dist_name
req_extensions = req_ext
prompt = no

[req_dist_name]
CN = $name

[req_ext]
subjectAltName = $san
EOF
}

function generate_certificate_request() {
    local name=$1
    echo "Generate certificate request $name.csr"
    openssl req -batch \
        -new -sha512 -noenc -newkey rsa:4096 \
        -config "$name".crt.conf \
        -keyout "$name".key -out "$name".csr
}

function sign_crt_with_ca() {
    local ca_crt=$1
    local ca_key=$2
    local name=$3

    echo "Sign certificate request $name.crt"

    openssl x509 -req -in "$name".csr \
        -CA "$ca_crt" -CAkey "$ca_key" \
        -extfile "$name".crt.conf \
        -extensions req_ext \
        -CAcreateserial -out "$name".crt \
        -days 10 -sha512
}

if [ ! -f custom-ca.key ]; then
    echo "Generate a mini Certificate Authority"
    openssl req -batch \
        -x509 -sha512 -nodes -days 10 -newkey rsa:4096 \
        -subj "/CN=Mini Certificate Authority" \
        -keyout custom-ca.key -out custom-ca.crt
fi

for service in parsec-{s3,server,proxy}; do
    if [ ! -f "$service".crt.conf ]; then
        generate_cert_conf "$service" DNS:"$service",DNS:localhost,IP:127.0.0.1
    fi

    # Generate key + csr if missing or if the key is older than the conf
    if [ ! -f "$service".key ] || [ "$service".key -ot "$service".crt.conf ]; then
        generate_certificate_request "$service"
    fi

    # Generate crt if missing or if it's older than the csr or the custom CA
    if [ ! -f "$service".crt ] || [ "$service".crt -ot "$service".csr ] || [ "$service".crt -ot custom-ca.key ]; then
        sign_crt_with_ca custom-ca.{crt,key} "$service"
    fi
done

if [ "$(stat -c %g parsec-server.key)" -ne 1234 ]; then
    echo "Changing group id of parsec-server.key to 1234"
    sudo chown "$USER":1234 parsec-server.key
fi

if [ "$(stat -c %a parsec-server.key)" -ne 640 ]; then
    echo "Changing permission of parsec-server.key to 640"
    chmod 640 parsec-server.key
fi

Set up the env files

The easiest way to configure the Parsec Sever is by using environment variables. These variables can be stored in a file and sourced before running the server.

In this guide, the environment variables are stored into multiple files in order to better describe how to configure each component.

The administration token

To be able to perform admin tasks (like creating an organization) on the server, an administration token is required. Below you will find a simple script to generate a token:

gen-admin-token.sh

# shellcheck disable=SC2148
set -euo pipefail

ENV_FILE=parsec-admin-token.env
if [ ! -f $ENV_FILE ]; then
    PARSEC_ADMINISTRATION_TOKEN=$(openssl rand -hex 32)
    echo "PARSEC_ADMINISTRATION_TOKEN=$PARSEC_ADMINISTRATION_TOKEN" > $ENV_FILE

    PARSEC_FAKE_ACCOUNT_PASSWORD_ALGORITHM_SEED=$(openssl rand -hex 32)
    echo "PARSEC_FAKE_ACCOUNT_PASSWORD_ALGORITHM_SEED=$PARSEC_FAKE_ACCOUNT_PASSWORD_ALGORITHM_SEED" >> $ENV_FILE

    echo "Parsec administration token generated in: $ENV_FILE"
else
    echo "Parsec administration token already exists in: $ENV_FILE"
fi

The script will generate a random token (openssl rand -hex 32) and create the env file parsec-admin-token.env.

The token doesn’t have to be a valid hexadecimal value: any string with enough entropy can be used. For example, it could be replaced by a value from a password-generator.

The script above also generates FAKE_ACCOUNT_PASSWORD_ALGORITHM_SEED which is a secret used to make unpredictable the password algorithm configuration returned for non-existing accounts.

Database env file

Create the file parsec-db.env and specify the the following content to configure the access to the PostgreSQL database:

parsec-db.env

# The PostgreSQL database URL
PARSEC_DB=postgresql://DB_USER:DB_PASS@parsec-postgres:5432/parsec

# The minimum number of connections to the database
PARSEC_DB_MIN_CONNECTIONS=5

# The maximum number of connections to the database
PARSEC_DB_MAX_CONNECTIONS=7

SMTP env file

Create the file parsec-smtp.env to configure the access to the SMTP server (mailhog in this case).

We need to set the connection information, the sender information, the default language the emails are sent in:

parsec-smtp.env

# The SMTP host to use for sending email
PARSEC_EMAIL_HOST=parsec-smtp

# The SMTP server port
PARSEC_EMAIL_PORT=1025

# The SMTP server username
PARSEC_EMAIL_HOST_USER=SMTP_USER

# The SMTP password
PARSEC_EMAIL_HOST_PASSWORD=SMTP_PASS

# The SMTP sender's email address
PARSEC_EMAIL_SENDER=parsec@test.xyz

# Enable to use TLS (secure) connection to connect to the SMTP server
# PARSEC_EMAIL_USE_SSL

# Enable to use implicit TLS (secure) connection to connect to the SMTP server
# PARSEC_EMAIL_USE_TLS

S3 env file

Create the file parsec-s3.env with the following content to set the URL for the S3-like service:

parsec-s3.env

# The blockstore configuration
#
# The syntax should be one of the following:
#
# - s3:[<endpoint_url>]:<region>:<bucket>:<key>:<secret>
# - swift:<auth_url>:<tenant>:<container>:<user>:<password>
# - POSTGRESQL
# - MOCKED
#
# For S3/Swift, <endpoint_url> & <auth_url> are considered as HTTPS by default
# (e.g."s3:foo.com:[...]" -> https://foo.com).
#
#   Note that escaping must be used in URLs in order to provide:
#   - a custom scheme (e.g. "s3:http\\://foo.com:[...]"")
#   - a port (e.g. "s3:parsec-s3\:9000:[...]")
#
# No extra parameter is needed for MOCKED (will use in-memory store) and
# POSTGRESQL (will use the same database specified in PARSEC_DB).
#
# Multiple blockstore can be provided to form a RAID0/1/5 cluster.
# In this case, each configuration must be provided with the following syntax:
# - <raid_type>:<node>:<config>
#  where <raid_type> is RAID0/RAID1/RAID5, <node> is an integer and
# `<config>` is one of the previous s3/swift/POSTGRESQL/MOCKED configuration.

PARSEC_BLOCKSTORE=s3:parsec-s3\:9000:region1:parsec:S3_ROOT_USER:S3_ROOT_PASS

Parsec env file

Create the file parsec.env with the following content to configure the parsec-server service:

parsec.env

# Host & Port to listen to.
PARSEC_HOST=0.0.0.0
PARSEC_PORT=6777

# The SSL key file.
PARSEC_SSL_KEYFILE=/run/secrets/parsec-pem-key

# The SSL certificate file.
PARSEC_SSL_CERTFILE=/run/secrets/parsec-pem-crt

# A comma-separated list of ciphers suites to use
# This is the list of suites recommended by ANSSI
# See: https://cyber.gouv.fr/guide-tls
PARSEC_SSL_CIPHERS=
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}TLS_AES_256_GCM_SHA384,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}TLS_AES_128_GCM_SHA256,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}TLS_AES_128_CCM_SHA256,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}TLS_CHACHA20_POLY1305_SHA256,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-ECDSA-AES256-GCM-SHA384,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-ECDSA-AES128-GCM-SHA256,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-ECDSA-AES256-CCM,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-ECDSA-AES128-CCM,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-ECDSA-CHACHA20-POLY1305,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-RSA-AES256-GCM-SHA384,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-RSA-AES128-GCM-SHA256,
PARSEC_SSL_CIPHERS=${PARSEC_SSL_CIPHERS}ECDHE-RSA-CHACHA20-POLY1305

# The log file (defaults to stderr)
# PARSEC_LOG_FILE=

# The log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
# Only log messages of the specified level (or above) will be displayed
# (e.g. WARNING will output WARNING + ERROR + CRITICAL messages)
PARSEC_LOG_LEVEL=WARNING

# The log message format (CONSOLE, JSON)
PARSEC_LOG_FORMAT=CONSOLE

# List of proxy addresses to trust
PARSEC_PROXY_TRUSTED_ADDRESS=parsec-proxy

# The URL to reach Parsec server
PARSEC_SERVER_ADDR=parsec3://example.com

# Keep SSE connection open by sending keepalive messages to client in seconds.
# Set to 0 to disable keepalive messages.
PARSEC_SSE_KEEPALIVE=30

# Sentry environment for telemetry report.
PARSEC_SENTRY_ENVIRONMENT=production

Parsec Server can be further configured with other environment variables. To see the full list, run the following command and look for sections such as [env var: VARIABLE] next to each configuration option. For example:

$ python -m parsec run --help

[...]

--administration-token TOKEN    Secret token to access the Administration API
                                [env var: PARSEC_ADMINISTRATION_TOKEN; required]

Deploy with Docker

This section describes how to install Parsec Server directly on Linux.

This method is an alternative to the Direct installation on Linux server.

Additional Requirements

In addition to the base requirements, you will need:

• Docker Engine

• Docker Compose (plugin)

The Docker Compose file

You can use the following Docker Compose file to deploy Parsec Server for testing:

parsec-server.docker.yaml

services:
  parsec-proxy:
    depends_on:
      - parsec-server
    image: nginx:1.27-alpine
    container_name: parsec-proxy
    ports:
      - 443:443
      - 80:80
    volumes:
      - ./parsec-nginx.conf:/etc/nginx/nginx.conf:ro
      - ./parsec-proxy.crt:/certs/proxy.crt:ro
      - ./parsec-proxy.key:/certs/proxy.key:ro

  parsec-postgres:
    image: postgres:16.10-alpine
    container_name: parsec-postgres
    environment:
      POSTGRES_USER: DB_USER
      POSTGRES_PASSWORD: DB_PASS
      POSTGRES_DB: parsec
    ports:
      # Expose PostgreSQL to localhost
      - 127.0.0.1:5432:5432
    volumes:
      - parsec-db-data:/var/lib/postgresql/data

  parsec-s3:
    image: quay.io/minio/minio:RELEASE.2024-09-13T20-26-02Z
    container_name: parsec-s3
    command: server --console-address ":9090" --certs-dir /opts/certs /data
    environment:
      MINIO_ROOT_USER: S3_ROOT_USER
      MINIO_ROOT_PASSWORD: S3_ROOT_PASS
    ports:
      # Admin console exposed to https://127.0.0.1:9090
      - 127.0.0.1:9090:9090
      # Expose S3 API to localhost
      - 127.0.0.1:9000:9000
    volumes:
      - parsec-object-data:/data
      - ./parsec-s3.key:/opts/certs/private.key:ro
      - ./parsec-s3.crt:/opts/certs/public.crt:ro
      - ./custom-ca.crt:/opts/certs/CAs/ca.test.crt:ro

  parsec-smtp:
    image: mailhog/mailhog:v1.0.1
    container_name: parsec-smtp
    ports:
      - 1025:1025
      # Web interface exposed to http://127.0.0.1:8025
      - 127.0.0.1:8025:8025

  parsec-server:
    depends_on:
      - parsec-smtp
      - parsec-s3
      - parsec-postgres
    image: ghcr.io/scille/parsec-cloud/parsec-server:3.9.0
    restart: on-failure
    container_name: parsec-server
    env_file:
      - parsec.env
      - parsec-s3.env
      - parsec-db.env
      - parsec-smtp.env
      - parsec-admin-token.env
    environment:
      AWS_CA_BUNDLE: /run/secrets/mini-ca-crt
    secrets:
      - mini-ca-crt
      - parsec-pem-crt
      - parsec-pem-key
    ports:
      - 127.0.0.1:6777:6777

volumes:
  parsec-db-data: {}
  parsec-object-data: {}

secrets:
  parsec-pem-crt:
    file: ./parsec-server.crt
  parsec-pem-key:
    file: ./parsec-server.key
  mini-ca-crt:
    file: ./custom-ca.crt

It will setup 4 services:

Service name	Description
parsec-postgres	The PostgreSQL database
parsec-s3	The Object Storage service
parsec-smtp	A mock SMTP server
parsec-server	The Parsec Server
parsec-proxy	A Nginx proxy server, used as an example to configure a reverse proxy. Learn more about using Parsec behind a reverse proxy

Starting the services

The docker containers can be started as follows:

docker compose -f parsec-server.docker.yaml up

Initial configuration

On the first start, a one-time configuration is required for the database and s3 services.

Applying the database migration

(Optional) Check that the database is accessible:

$ set -a
$ source parsec-db.env
$ docker exec -t parsec-postgres psql 'postgresql://DB_USER:DB_PASS@0.0.0.0:5432/parsec' \
            -c "\conninfo"
...
You are connected to database "parsec" as user "parsec" on host "0.0.0.0" at port "5432".

To bootstrap the database, apply the migrations:

docker compose -f parsec-server.docker.yaml run parsec-server migrate

Create the S3 Bucket

Access the console at https://127.0.0.1:9090. You will need to use the credential specified in parsec-server.docker.yaml:

parsec-server.docker.yaml

      MINIO_ROOT_USER: S3_ROOT_USER
      MINIO_ROOT_PASSWORD: S3_ROOT_PASS

Go to https://127.0.0.1:9090/buckets/add-bucket to create a new bucket named parsec with the features object locking toggled on.

After that you will need to restart the parsec-server (that likely exited because it wasn’t able to access the S3 bucket):

docker compose -f parsec-server.docker.yaml restart parsec-server

Test the SMTP configuration & server

You can test mailhog with the following script:

ping-mailhog.sh

# shellcheck disable=SC2148
set -a
source parsec-smtp.env

curl \
    --url "smtp://127.0.0.1:$PARSEC_EMAIL_PORT" \
    --user "$PARSEC_EMAIL_HOST_USER@localhost:$PARSEC_EMAIL_HOST_PASSWORD" \
    --mail-from "$PARSEC_EMAIL_SENDER" \
    --mail-rcpt rcpt@test.com \
    --upload-file <(date --rfc-3339=seconds)

You can then check if the email is present in the web interface at http://127.0.0.1:8025

Deploy with Linux

This section describes how to install Parsec Server directly on Linux.

This method is an alternative to the Container-Based deployment.

Additional Requirements

In addition to the base requirements, you will need:

• Python v3.12 with pip and venv modules

• Parsec Server (Python package), available at https://pypi.org/project/parsec-cloud/

  • It can be installed with pip (see Installation step below).

  • To perform an offline install, you will need to download the package and all its dependencies. You can do this with pip download.

Set up

Configure the env files as described in Set up the env files.

Installation

1. Set up a virtual env:

   python -m venv venv
   

2. Activate the virtual env in your current shell:

   source venv/bin/activate
   

3. Install Parsec Server:

   python -m pip install 'parsec-cloud==3.9.0'
   

4. Apply database migrations:

   $ set -a
   $ source parsec-db.env
   $ python -m parsec migrate
   

Start the server

1. Create a wrapper script run-parsec-server with the following content:

   run-parsec-server

   # Load the virtual env
   source venv/bin/activate
   
   # Load the env files into the environment table
   set -a
   source parsec-admin-token.env
   source parsec-db.env
   source parsec-smtp.env
   source parsec-s3.env
   source parsec.env
   set +a
   
   # Start Parsec Server
   python -m parsec run
   

2. Make the script executable

   chmod +x run-parsec-server
   

3. Start Parsec Server with the wrapper:

   ./run-parsec-server
   

Start using Parsec Server

Create an Organization

Follow the steps below to create an Organization (replace ORG_NAME with the desired name for your organization)

1. Create the organization

   $ set -a
   $ source parsec-admin-token.env
   $ export SSL_CAFILE=$PWD/custom-ca.crt
   $ parsec-cli organization create --addr parsec3://127.0.0.1:6777
   [...]
   Bootstrap organization url: [...]
   

   Save the Bootstrap organization url to create the first user (owner) of the Organization.

2. Start Parsec with the custom CA:

   $ export SSL_CAFILE=$PWD/custom-ca.crt
   $ parsec
   

3. Bootstrap the Organization (create its first User)

   1. Got to Menu ‣ Join an organization`

   2. Paste the Bootstrap organization url from before (should already be filled in the text field)

   3. Follow the instructions to create the first user of the Organization.

Running behind a reverse proxy

To run Parsec behind a reverse proxy you will need to add the option --proxy-trusted-address or set the environment variable PARSEC_PROXY_TRUSTED_ADDRESS to the address of the reverse proxy (e.g.: localhost).

If this option is not set, the gunicorn/uvicorn FORWARDED_ALLOW_IPS environment variable is used, defaulting to trusting only localhost if absent.

Tip

You can provide multiple addresses by separating them with a comma. For example: --proxy-trusted-address '::1,10.0.0.42' will trust the addresses ::1 and 10.0.0.42

An example of a reverse proxy configuration for nginx can be found in the Docker Compose file:

parsec-server.docker.yaml

  parsec-proxy:
    depends_on:
      - parsec-server
    image: nginx:1.27-alpine
    container_name: parsec-proxy
    ports:
      - 443:443
      - 80:80
    volumes:
      - ./parsec-nginx.conf:/etc/nginx/nginx.conf:ro
      - ./parsec-proxy.crt:/certs/proxy.crt:ro
      - ./parsec-proxy.key:/certs/proxy.key:ro

Use the following Nginx configuration file to serve the domain example.com by listening on port 80 and 443, and proxy the requests to the Parsec Server.

parsec-nginx.conf

events {
    worker_connections 128;
}


http {
    server {
        listen 80;
        listen 443 ssl;
        server_name example.com;
        http2 on;
        # Hide version number
        server_tokens off;

        # Only provide tlsv1.3
        ssl_protocols       TLSv1.3;
        ssl_certificate     /certs/proxy.crt;
        ssl_certificate_key /certs/proxy.key;

        location ~ ^/authenticated/.*/events$ {
            proxy_pass https://parsec-server:6777;

            # Specific configuration for SSE:
            # Disable buffering, cache & chunking
            proxy_buffering             off;
            proxy_cache                 off;
            chunked_transfer_encoding   off;
            proxy_read_timeout          24h;

            # Add X-Forwarded headers to the proxied request
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Port $server_port;

            # Remove the Forwarded header
            proxy_set_header Forwarded "";

            # Overwrite the Host header
            proxy_set_header Host example.com;

        }

        location / {
            proxy_pass https://parsec-server:6777;

            # Add X-Forwarded headers to the proxied request
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Port $server_port;

            # Remove the Forwarded header
            proxy_set_header Forwarded "";

            # Overwrite the Host header
            proxy_set_header Host example.com;
        }
    }
}

The important takeaways are:

• Set the X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port headers.

  • Currently, Parsec only uses the X-Forwarded-For and X-Forwarded-Proto headers, but it is better to set all of them to avoid any issue.

• Remove the Forwarded header.

  • The Forwarded header (RFC-7239) is not used by Parsec, but it may be in the future.

• Set the header host to the accessible address. Here we force the value to be example.com, but you can set it to $host like for X-Forwarded-Host.

TLS Recommendation

We recommend that connections to the service are made using a TLS layer. If you are using a reverse proxy refer to it’s documentation on how to configure TLS:

• Nginx SSL module configuration

• Apache httpd SSL Howto

• Traefik TLS configuration

Or if you do not use a reverse proxy, see how to configure TLS on the server.

TLS Server configuration

We recommend that when user directly connects to the server (i.e. without using a reverse proxy) to configure the TLS settings on the server.

We provide 3 options to configure the TLS connection:

• --ssl-keyfile (PARSEC_SSL_KEYFILE): The TLS key file

• --ssl-certfile (PARSEC_SSL_CERTFILE): The TLS certificate file

• --ssl-ciphers (PARSEC_SSL_CIPHERS): A list of ciphers that can be used when the client & server negotiate which algorithm to use when doing the TLS handcheck

  Note

  You are not required to provide the ciphers list as we use a default list that was recommended by the French Cybersecurity Agency (ANSSI) in Recommandations de sécurité relatives à TLS

If you followed the installation described in Deploy with Docker, you should only have to replace the file s parsec-server.crt and parsec-server.key that where generated on section TLS certificates. The env variables PARSEC_SSL_KEYFILE and PARSEC_SSL_CERTFILE are already configured in parsec.env (see Parsec env file).