Operating System CentOS

How to Install Parse Server on AlmaLinux 9 and Rocky Linux 9

Set up Parse Server 9 with Node.js 22 and MongoDB 8.0 on AlmaLinux 9 or Rocky Linux 9, as a systemd service behind an HTTPS reverse proxy.

Parse Server is the open source backend that replaced the hosted Parse service: a Node.js application that gives mobile and web apps a REST and GraphQL API, user accounts, file storage and cloud functions on top of MongoDB or PostgreSQL. This guide installs the current Parse Server 9 with MongoDB 8.0 on AlmaLinux 9 or Rocky Linux 9 (the steps also apply to CentOS Stream 9 and RHEL 9), runs it as a systemd service and tests it with curl. CentOS 7 reached end of life on 30 June 2024 and cannot run a supported Node.js release, so the 9 family is the platform to use.

Requirements

  • An AlmaLinux 9 or Rocky Linux 9 server (x86_64) with at least 2 GB of RAM and a user with sudo rights.
  • Node.js 20, 22, 24 or 26. Parse Server 9 declares support for 20.19+, 22.13+, 24.11+ and 26.13+. This guide uses the Node.js 22 module stream from AppStream.
  • MongoDB 7 or 8 (8.0.4 or newer for the 8.0 series), or PostgreSQL 16 to 18 with PostGIS. This guide uses MongoDB 8.0 from MongoDB's own repository.
  • A domain name such as parse.example.com if clients on the internet will connect.

Step 1: Update the system and install Node.js

sudo dnf update -y
sudo dnf module reset nodejs -y
sudo dnf module enable nodejs:22 -y
sudo dnf install -y nodejs npm

Check the version. It must be 22.13.0 or newer:

node --version

Step 2: Install MongoDB 8.0

MongoDB is not in the distribution repositories. Add the official repository:

sudo tee /etc/yum.repos.d/mongodb-org-8.0.repo <<'EOF'
[mongodb-org-8.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/9/mongodb-org/8.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-8.0.asc
EOF

Install the server and shell, then start the service:

sudo dnf install -y mongodb-org
sudo systemctl enable --now mongod
sudo systemctl status mongod

MongoDB listens only on 127.0.0.1:27017 by default, which is what you want when Parse Server runs on the same machine. Do not change bindIp in /etc/mongod.conf unless you also enable authentication.

Step 3: Install Parse Server

Create a dedicated system user and install Parse Server into its own directory, so that the service does not run as root and upgrades do not touch system-wide packages.

sudo useradd --system --create-home --home-dir /opt/parse --shell /sbin/nologin parse
sudo -u parse bash -c 'cd /opt/parse && npm init -y && npm install parse-server'

Generate two random secrets, one for the application ID and one for the master key. Run the command twice and keep both values:

openssl rand -hex 32

Step 4: Create the configuration file

Parse Server reads its options from a JSON file passed on the command line. Create /opt/parse/config.json with sudo vi /opt/parse/config.json and insert your own values:

{
  "appId": "YOUR_APP_ID",
  "masterKey": "YOUR_MASTER_KEY",
  "appName": "MyApp",
  "databaseURI": "mongodb://127.0.0.1:27017/parse",
  "host": "127.0.0.1",
  "port": 1337,
  "mountPath": "/parse",
  "serverURL": "http://127.0.0.1:1337/parse",
  "publicServerURL": "https://parse.example.com/parse"
}

Setting host to 127.0.0.1 keeps the API off the public interface (the default is 0.0.0.0); a reverse proxy will publish it over HTTPS in step 7. The file contains the master key, which bypasses all access controls, so restrict it:

sudo chown parse:parse /opt/parse/config.json
sudo chmod 600 /opt/parse/config.json

Step 5: Run Parse Server as a systemd service

Create /etc/systemd/system/parse-server.service:

[Unit]
Description=Parse Server
After=network.target mongod.service
Wants=mongod.service

[Service]
User=parse
Group=parse
WorkingDirectory=/opt/parse
Environment=NODE_ENV=production
ExecStart=/usr/bin/node /opt/parse/node_modules/parse-server/bin/parse-server /opt/parse/config.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Load the unit and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now parse-server
sudo journalctl -u parse-server -n 30 --no-pager

The log should end with a line saying that parse-server is running on http://127.0.0.1:1337/parse. Parse Server also writes log files to a logs folder in its working directory; set the PARSE_SERVER_LOGS_FOLDER environment variable in the unit to move them.

Step 6: Test the API

Check the health endpoint first. A healthy server answers with the status ok:

curl http://127.0.0.1:1337/parse/health

Store an object. Clients are not allowed to create new classes by default (allowClientClassCreation is false), so the first write to a new class needs the master key. The master key is accepted only from localhost unless you change masterKeyIps.

curl -X POST \
  -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"score":1337,"playerName":"deploy","cheatMode":false}' \
  http://127.0.0.1:1337/parse/classes/GameScore

The response contains an objectId and a createdAt timestamp. Read the class back:

curl -H "X-Parse-Application-Id: YOUR_APP_ID" \
  -H "X-Parse-Master-Key: YOUR_MASTER_KEY" \
  http://127.0.0.1:1337/parse/classes/GameScore

Step 7: Publish the API over HTTPS

Application IDs, session tokens and user passwords travel in every request, so never expose port 1337 directly. Put NGINX in front and terminate TLS there:

sudo dnf install -y nginx
sudo setsebool -P httpd_can_network_connect 1
sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Create /etc/nginx/conf.d/parse.conf:

server {
    listen 80;
    server_name parse.example.com;

    location /parse/ {
        proxy_pass http://127.0.0.1:1337/parse/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
sudo nginx -t
sudo systemctl enable --now nginx

Then obtain a certificate for the domain (for example with Certbot) and make sure publicServerURL in config.json matches the final HTTPS address. The setsebool command is required because SELinux otherwise stops NGINX from connecting to a local backend port.

Maintenance

  • Updates: run sudo -u parse bash -c 'cd /opt/parse && npm update parse-server' for releases within the same major version, then sudo systemctl restart parse-server. Read the changelog before moving to a new major version, because each one removes deprecated options and raises the minimum Node.js and database versions.
  • Backups: all application data lives in MongoDB. Dump it regularly with mongodump --db parse --out /var/backups/parse and copy the result off the server.
  • Database access control: for anything beyond a single-host setup, enable MongoDB authentication, create a user for the parse database and put the credentials into databaseURI.

The full option list is in the Parse Server README; you can also print it with node /opt/parse/node_modules/parse-server/bin/parse-server --help. MongoDB's steps are documented in its Red Hat installation guide.

Frequently asked questions

Can I use PostgreSQL instead of MongoDB?

Yes. Parse Server supports PostgreSQL with the PostGIS extension. Set databaseURI to a postgres:// connection string and skip the MongoDB step. Check the compatibility table in the README for the PostgreSQL versions your Parse Server release supports.

How do I get a web interface for my data?

Parse Dashboard is a separate npm package (parse-dashboard) that connects to your server with the application ID and master key. Because it uses the master key, the server must list the dashboard host in masterKeyIps if the two do not run on the same machine, and the dashboard itself must be served over HTTPS with its own login.

Why does a request with only the application ID fail with a permission error?

Current releases are locked down by default: clients cannot create classes, and the master key works only from localhost. Create your classes and their class-level permissions with the master key or the dashboard first, then let clients read and write within those rules.

Is the client key or REST API key still needed?

No. They are optional. If you do not configure them, the application ID alone identifies your app, and security comes from class-level permissions, ACLs and user sessions.

Share story:

Continue reading other guides on How VPS.