Installation

This guide is about installing a public CryptPad instance available on the internet. For instructions about installing and running a local development instance please see the Developer Guide.

Prerequisites

Domains

2 domains or subdomains are needed to take full advantage of CryptPad’s security features. Please see the domains section below for more details.

Hardware

The development team uses and recommends the following hardware requirements as a minimum on the host machine:

  • Debian 12

  • 2GB RAM

  • 2 CPUs

  • 20GB storage (depending on planned usage)

Warnung

CryptPad is engineered to maximise privacy, and to minimize the amount of useful information that can be gained even if the host machine is compromised. However it is up to the administrator(s) to ensure that the host machine is secure. The instructions for this are beyond the scope of this guide but best practices include:

  • Disabling password-based SSH access

  • Updating the operating system regularly with any security patches

  • Limiting the number of people who have server access

  • Avoiding insecure applications running in parallel on the same host

  • Updating CryptPad itself regularly

Software

Before starting the installation, ensure the following software is installed:

Install Cryptpad

Docker

While we still prefer the recommended installation method, Docker is now officially supported.

We provide the following files in the CryptPad repository:

  • .dockerignore is useful to remove parts of the repository from the image (avoid making it use too much storage)

  • Dockerfile is used to build the Docker image itself

  • docker-entrypoint.sh allows to configure a few things (domain names and build static assets)

  • docker-compose.yml used to create a container using the image and keep it running

  1. Build your own Docker image

    docker build -t cryptpad/cryptpad:version-5.6.0 .
    
  2. Modify docker-compose.yml with your own values

    • CPAD_MAIN_DOMAIN

    • CPAD_SANDBOX_DOMAIN

  3. Set appropriate permissions

    sudo chown -R 4001:4001 data customize
    
  4. Run the container with Docker Compose

    docker compose up -d
    

Note that you'll still need to follow the CryptPad configuration steps, especially Configure administrators. To do that you can mount your config.js file as a Docker volume.

volumes:
- ./data/blob:/cryptpad/blob
- ./data/block:/cryptpad/block
- ./customize:/cryptpad/customize
- ./data/data:/cryptpad/data
- ./data/files:/cryptpad/datastore
- ./config/config.js:/cryptpad/config/config.js

Domains

You need two domains to take full advantage of CryptPad’s security features.

  1. The main domain on which users access your instance

  2. A “sandbox” domain or subdomain to which a set of restrictive Content-Security Policy headers are applied

Warnung

Using CryptPad in production without the sandboxing system may put users’ information at risk.

The intent of this system is to limit the risk of Cross-Site Scripting (XSS) vulnerabilities allowing attackers to leak user data. Sensitive computation (like the processing of cryptographic keys) is handled on the main domain, while the user-interface is implemented on the sandbox domain.

The example Nginx configuration file includes the relevant entries to enable the sandboxing system, however, you must configure your instance correctly for it to be effective. You will need:

  1. two domains or subdomains

  2. to include both domains in cryptpad/config/config.js as described in Configure CryptPad

  3. to generate one TLS certificate that covers both domains. The development team uses acme.sh and this is reflected in the example config.

  4. to correctly assign both domains and certificates to the example Nginx configuration

Bemerkung

Thanks to community contributions, example configuration files for other reverse proxies than Nginx are also available in the docs folder. Please be aware that those are community supported and not officialy supported by the development team.

Install and configure Nginx

CryptPad’s application server handles active connections via websocket and serves static assets (HTML, Javascript, CSS, etc.). This basic configuration is designed to be very easy to configure for small to midsize instances (up to 3000 concurrent users). In a production environment, the development team recommends Nginx with our advanced example configuration for the following reasons:

  1. Scale to many more users by serving static content with a more scalable web-server instead of the single-threaded NodeJS web-server that is built-in

  2. Allow the application server to focus exclusively on handling websocket connections

Warnung

CryptPad cannot run in a subfolder. Make sure you configure your server to access it through the root domain or a subdomain.

Note that the version of Nginx distributed by your operating system may not support websockets. We recommend and only support Nginx stable.

To configure Nginx for CryptPad:

  1. Copy the example config file so that it is used/imported by the main Nginx config, for example by placing it in /etc/nginx/conf.d/cryptpad.conf

    • Basic example for small and midsize instances, where everything is processed by NodeJS

    • Advanced example for big instances, where Nginx handle static content and only websocket connections are processed by NodeJS

  2. Edit the configuration file with the correct domains and paths to certificates.

  3. Run openssl dhparam -out /etc/nginx/dhparam.pem 4096 if you haven’t done so already on the host machine.

Static assets and pages such as https://cryptpad.yourdomain.com/index.html should now be accessible at the main domain.

Configure CryptPad

To finalise the installation, ensure cryptpad/config/config.js contains at least:

  • The correct domains:

    • The main domain in place of:

      httpUnsafeOrigin: 'http://localhost:3000',
      
    • The Sandbox domain in place of:

      httpSafeOrigin: "https://some-other-domain.xyz",
      

Diagnostics

CryptPad provides a diagnostics page that runs instance configuration tests. Visit https://cryptpad.yourdomain.com/checkup/ after completing all of the steps above to ensure everything is correctly configured.

Configure administrators

Once CryptPad is installed, create an account via the Register button on the home page. To make this account an instance administrator:

  1. Copy their public key found in User Menu (avatar at the top right) > Settings > Account > Public Signing Key

  2. Paste this key in cryptpad/config/config.js in the following array (uncomment and replace the placeholder):

adminKeys: [
        "[cryptpad-user1@my.awesome.website/YZgXQxKR0Rcb6r6CmxHPdAGLVludrAF2lEnkbx1vVOo=]",
],
  1. Restart CryptPad

Configure support mailbox

The support mailbox can be configured from the Administration panel.

  1. With an instance administrator account, visit the /admin/#support page

  2. Click Generate Support Keys

  3. The support mailbox is now active

  4. Flush the cache to access the mailbox: General tab > Flush HTTP Cache

To allow other administrators to access the support mailbox:

  1. Copy the key at the bottom of the support page

  2. Send it to another administrator account

  3. They can use the Add private key field on the support page to gain access to the support mailbox

Build static pages & Open Graph metadata

To build some of CryptPad static pages & enable social media link previews, run the following command:

npm run build

This creates an index.html page for each application in the customize/www directory. It is not recommended to perform manual modifications on these pages as they will be overridden the next time npm run build is run.

To modify the preview images please see Open Graph preview images

Bemerkung

Updating to a newer version of the software in the future without re-running this command may result in outdated code.

Support

The development team is available to provide paid support contracts (see our organizational plans for an idea of our pricing), otherwise, requests for assistance can be directed to the community.

We recommend you to go over our forum and or admins Matrix channel.

Note that community support is provided by volunteers, please be aware of what you are asking of them and respect our Code of Conduct at all time.