This guide covers the installation procedure for the Parsec server (also called parsec-backend).
- Docker and the docker-compose plugin.
- Parsec client (Linux).
The Parsec server depends on the following external components in order to work properly:
- A PostgreSQL database to store the metadata.
An S3 object storage to store the data blocks.
Note
The Parsec server need access to an
S3 object storage
-like service, not necessarilyAWS S3
- An SMTP server for sending emails.
- A TSL/SSL server certificate for
HTTPS
communication with the clients. - (Optional) A Sentry DSN for telemetry report.
Warning
For security reasons, the installation of these components is outside the scope of this guide. In order to securely configure and manage them, please refer to their official documentations.
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.
For this guide, the required TLS certificates will be generated with a custom Certificate Authority (CA) created for this purpose.
setup-tls.sh
The script will:
- Generate the CA key & self-signed certificate (
custom-ca.{key,crt}
). - For
parsec-s3
andparsec-backend
services:- Generate the service key & Certificate Signing Request (CSR)
parsec-{service}.{key,csr}
. - Generate the certificate using the CSR and the CA.
- Generate the service key & Certificate Signing Request (CSR)
For the service
parsec-backend
:- Change the group id of the key file to
1234
(That is the GID used by theparsec-server
container). - Change the file mode to give read permission to the group
1234
.
Note
This is required because
docker-compose
does not allow to mount the file with the correct permissions in the container.- Change the group id of the key file to
Warning
For production, you should use certificates issued from a trusted CA
We split the configuration of the parsec server into multiple env files so it's simpler to understand how to configure each part.
To be able to perform admin tasks (like creating an organization) on the backend, an administration token is required. Below you will find a simple script to generate a token:
gen-admin-token.sh
The script will generate a random token (openssl rand 63 | base64 --wrap=86
) and create the env file parsec-admin-token.env
Note
The step TOKEN=$(openssl rand 63 | base64 --wrap=86)
could also be replaced by a value generated by a password-generator for example.
It doesn't need to be encoded in base64
(we encode it in the script just to have printable characters).
Create the file parsec-db.env
with the following content to configure the access to the PostgreSQL database:
parsec-db.env
Create the file parsec-smtp.env
to configure the access to the SMTP server (mailhog
in this case).
We need to set the connection informations, the sender information, in which the default language the emails are sent:
parsec-smtp.env
Create the file parsec-s3.env
with the following content to set the URL for the S3-like service:
parsec-s3.env
Note
We need to escape the :
with a \
when specifying the port of the service.
Create the file parsec.env
with the following content to configure the parsec-backend
service:
parsec.env
You can use the following docker-compose file (parsec-server.docker.yaml
) to deploy the Parsec server for testing:
parsec-server.docker.yaml
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-backend |
The Parsec server |
The docker containers can be started as follow:
docker compose -f parsec-server.docker.yaml up
On the first start, a one-time configuration is required for the database and s3 services.
(optional) Check that the database is accessible with:
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"
Note
You should have something like display on your console:
You are connected to database "parsec" as user "parsec" on host "0.0.0.0" at port "5432".
To bootstrap the database we just need to apply the migrations with:
docker compose -f parsec-server.docker.yaml run parsec-backend migrate
Access the console at https://127.0.0.1:9090, you will need to use the credential specified in the docker-compose
file at services.parsec-s3.environment.MINIO_ROOT_{USER,PASSWORD}
.
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-backend
(that likely exited because it wasn't able to access the S3 bucket):
docker compose -f parsec-server.docker.yaml restart parsec-backend
You can test mailhog
with:
ping-mailhog.sh
You can then check if the email is present in the web interface at http://127.0.0.1:8025
set -a
source parsec-admin-token.env
export SSL_CAFILE=$PWD/custom-ca.crt
parsec.cli core create_organization --addr parsec://127.0.0.1:6777 <orgname>
Note
Change <orgname>
to the organization's name that suit you.
Save the link after Bootstrap organization url:
you will need it to create the first user (owner) of the organization.
First, start parsec
with the custom CA:
export SSL_CAFILE=$PWD/custom-ca.crt
parsec
After that go to Menu
/Join an organization
(or CTRL+O
) and paste the link from before (should already be filled in the text field). Follow the instructions to create the first user of the organization.