Hosting FastComments On Prem

FastComments provides several solutions for deployment. The most common is where we host the application for you.

However, we understand some customers cannot store their information in the cloud, and require hosting all of their data on-premises.

This documentation covers that use case.

What's Included Internal Link

FastComments On Prem allows you to deploy our live commenting solution, including all moderation and admin tools, on your own hardware.

This means that you have control over your data, and the commenting system can be restricted to your local LAN or corporate network.

Instances Internal Link

Required Components

For On-Prem, FastComments just consists of an application server and a database. We have simplified the deployment so that the application can serve all traffic directly without adding other components.

The application server is provided in a Docker image and can be deployed with any container management solution.

The database, MongoDB, can be self-ran or hosted by another provider like AWS DocumentDB or MongoDB Atlas.

FastComments is currently tested with MongoDB 7, however we aim to be DocumentDB compatible to ease deployment.

Instance Sizes

You will find that FastComments is fairly well optimized and doesn't require large machines for the application itself to keep low P99s.

All batch and cron jobs use streaming to limit total memory usage.

The below tables for the application server and database can assist with sizing.

Application Server Instances

Concurrent Users Total Cluster CPUs Total Cluster Memory
100 1 256mb
1K 2 512mb
10K 8 1gb
100K 32 8gb
1M 64 64gb

For example, a single core serving around 100 comment threads a second usually never uses more than 250mb RSS.

Database Server Instances

Sizing the database depends on working set size, which is the amount of data you access at a given point in time, as well as concurrent requests.

FastComments is fairly kind to Mongo, in that for the hot queries it uses index hints, streaming cursors, and has concurrency limits in various areas to prevent overloading of downstream systems.

The below is a general guideline on database instance sizes. Note that this is per instance, not total resources in the cluster.

Concurrent Users Comments Stored CPUs Per Instance Memory Per Instance
100 1k 1 256mb
1K 5k 2 512mb
10K 100k 8 2gb
100K 500k 16 8gb
1M 5M 32 32gb

The above tables are conservative estimates. You may find actual requirements differ based on your specific configuration (page sizes, comment volume, etc).

Config Internal Link

FastComments utilizes environment variables for configuration. The following list outlines all supported variables that are relevant to On-Prem.

Variable Default Info Required Examples or Valid Values
NODE_ENV Environment type. Yes production, dev
MONGO_URI DB Connection URI. Yes
MONGO_ENABLE_SSL false Enables using SSL to connect to the database. No true, false
MONGO_ENABLE_SSL_VALIDATE false Enables validating the cert against the CA when connecting to Mongo. No true, false
MONGO_SSL_CA Mongo SSL CA pem file. No /path/to/some-cert.pem
ADMIN_NOTIFICATIONS_EMAIL Email where important system-related notifications should go. No
IP_HASH_SALT Salt for hashing IP addresses. Yes
SESSION_SECRET The key used to sign sessions. Yes
SESSION_STORE_SECRET The key used to sign/hash sessions in storage. Must be different than SESSION_SECRET. Yes
HOSTNAME The hostname where FastComments is deployed (admin dashboard etc). Should NOT include port or protocol. Yes
HOST_ADDR An accessible URI where FastComments is deployed (admin dashboard etc). Yes
EMAIL_CONFIG_PATH A path on the local file system where the email config (SMTP, domain/provider mappings, etc) is. Yes /my/config.json
EMAIL_DEFAULT_FROM_NAME FastComments Robot Email "From Name" header. No My Company Name
EMAIL_DEFAULT_FOOTER_LOGO /images/logo-32-2020-01.png Email footer logo. No
EMAIL_DEFAULT_TRANSPORT Override for "defaultTransport" in EMAIL_CONFIG_PATH. Useful for deploying same config file to different envs. No myTransportName
ON_PREM_TENANT_ID The ID of your account on Used to register your license key. No
ON_PREM_LICENSE_KEY An on-prem license key. No
GIPHY_API_KEY Giphy API Key. If not specified, you should create a config rule that disables the gif picker. No
GIPHY_DEFAULT_RATING pg Used for giphy integration. Can also be overridden with widget customization rules. No g, pg, pg-13, r
OPENAI_SECRET_KEY Used for openai powered features like optional GPT-based spam detection. No
CDN_HOST_ADDR The hostname where assets will be fetched from. Defaults to value of HOSTNAME. No
LARGE_FILE_HOST_ADDR The hostname where large files (like exports) are fetched from. Defaults to value of CDN_HOST_ADDR. No
LARGE_FILE_LOCATION_TYPE local_disk Where large files, like exports, should be stored. No local_disk, s3
FROM_EMAIL_HOST The hostname where emails should be sent from. No
COOKIE_ID fastcomments.sid The name of the fastcomments cookie. No
COOKIE_HOSTNAME The value of the cookie "hostname" field. Recommended to prefix with dot. No
S3_ACCESS_KEY Used for user file uploads, avatars, etc. Defaults to local FS if undefined. No
S3_SECRET_KEY Used for user file uploads, avatars, etc. No
S3_REGION Used for user file uploads, avatars, etc. No
S3_BUCKET Used for user file uploads, avatars, etc. No
S3_HOST Used for user file uploads, avatars, etc. No
CACHE_DIR Location to store optional offline cache, for when DB is not available. Periodically refreshed with top 100 comment threads. No
BACKUP_DIR Location to store data for when DB is not available. If a comment is submitted when the DB is not available, it goes here, and is processed later. No

Note that all domain-related variables use the _HOST or _ADDR postfix. The difference is:

  • _HOST:
  • _ADDR:

The EMAIL_CONFIG_PATH should contain a path to a JSON file with the following example format:

Email Config
Copy Copy
3 "defaultDKIM": {
4 "domainName": "",
5 "keySelector": "2024",
6 "privateKey": "-----BEGIN PRIVATE KEY-----\nABCDEFG\n-----END PRIVATE KEY-----"
7 },
8 "providerTransports": {
9 "": "specialTransport"
10 },
11 "defaultTransport": "mailgun",
12 "transports": {
13 "mailgun": {
14 "host": "",
15 "port": 587,
16 "secure": false,
17 "auth": {
18 "user": "",
19 "pass": "password"
20 },
21 "tls": {
22 "ciphers": "SSLv3"
23 }
24 },
25 "specialTransport": {
26 "host": "",
27 "port": 587,
28 "secure": false,
29 "auth": {
30 "user": "",
31 "pass": "password"
32 },
33 "tls": {
34 "ciphers": "SSLv3"
35 }
36 }
37 }

In the above example we define a default SMTP email transport called mailgun. We also define special transport that we use specifically for emails. In some scenarios it is desirable to use a specific provider or sending IP for a domain to tune delivery. This is optional.


When connecting to DocumentDB you will want to specify MONGO_ENABLE_SSL=true MONGO_SSL_CA=/some/path.pem to be compatible with default settings.

Database Downtime and Maintenance Mode Internal Link

FastComments supports an automatic maintenance mode. If the database goes down, it can continue to serve popular comment threads.

Additionally, in maintenance mode, all comments are saved to BACKUP_DIR. They will be processed (checked for spam, etc) and saved once the system is back online.

It does this by, every hour, determining the top 100 most popular comment threads and caching their content on-disk. Determining the top 100 threads is already done from pre-calculated state, so it is not a heavy periodic job.

This is completely optional, and is only enabled if CACHE_DIR and BACKUP_DIR are set. This of course makes the application nodes stateful, however it is state that can be lost anytime without causing the application to misbehave.

Note that in maintenance mode proper authentication of comment threads cannot be done, so only threads that are safely considered public are periodically backed up.

In maintenance mode many features are not available.

Widget Code Internal Link

The front end code snippets and libraries for On-Prem are the same as the SaaS product. However, you must specify apiHost and the correct script path:

Comments Code for On Prem
Copy Copy
2<script src=""></script>
3<div id="fastcomments-widget"></div>
5 FastCommentsUI(document.getElementById('fastcomments-widget'), {
6 tenantId: "demo",
7 apiHost: ""
8 // ... can also pass SSO payload etc.
9 });

The above is a very simple example. We could also use the 1st-party React, Angular, Vue, Svelte, etc, libraries.

API Internal Link

The API can be accessed just like the regular SaaS product in that you would log into the On-Prem dashboard to create API keys and use those keys to access the API. The API endpoints are the same on-prem as they are for the SaaS product.

Multiple Domains Internal Link

Your On-Prem FastComments installation can serve comments to multiple internal domains, for example and You can configure these separately but host them on one On-Prem setup by creating separate Customization Rules to configure their individual behaviors.

Security Internal Link

By default, FastComments assumes comment threads are public. To add a layer of security, it's recommended to create a Customization Rule with the Requires SSO option checked. This will cause all comment related endpoints to require SSO authentication.

In Conclusion

You've reached the end of the On Prem documentation. Let us know what further comments or questions you have below - you may also reach out to us via the Support Page.