Keep on top of it all with Herda 🐄
- Node.js v20
- Docker Desktop or Docker Engine (your preference)
If you prefer not to use Docker, you can set up MongoDB Community Server v7 manually. This documentation targets a Docker-based workflow and you will need to make any adjustments yourself.
⚠️ This software is untested with other versions of MongoDB!
If you are planning to develop Herda, it is recommended to use nvm to help ensure you are running the correct version of Node.
Getting started developing Herda is simple, as both apps use development-friendly default configuration, with one exception: you are advised to set a static JWT secret. (If you don't, one will be generated randomly when the server starts up that can be used for a demo, but it won't persist through a restart.)
Run the following snippet to generate a static secret:
echo 'console.log(require("crypto").randomBytes(64).toString("hex"))' |\
node - |\
xargs -I{} echo "AUTH_JWT_SECRET={}" >> .envYou are now ready to start up services. First, start MongoDB:
docker compose up mongo -dAfter MongoDB has started and initialized, install and start the server:
# Install dependencies
npm install
# Start the server app
npm run devOpen http://localhost:5001/api in your browser. If you receive a JSON response including "Herda Server" and a version number, then it's up and running.
To run the PWA, open a separate terminal in the web directory and run similar setup commands:
# Install dependencies
npm install
# Start the PWA
npm run devOpen the URL shown in the terminal - most likely http://localhost:5173. If you see a login page, and the version number you saw in the API response earlier is displayed in the bottom left corner, then everything is connected up and you're all set.
ℹ️ Both the server and PWA reload automatically when their source code is changed, so there's no need to manually stop and restart them unless you change a dependency.
When you are finished working on Herda and want to teardown the work environment, exit the npm processes (Ctrl-C or Cmd-C) and run docker compose stop mongo to exit MongoDB.
An alternative approach to running Herda is to build a Docker image which runs both the headless API and frontend statically. This is primarily intended for production use. The Dockerfile handles building the app into a distributable image, and you just need to configure its environment.
# Generate static JWT secret
echo 'console.log(require("crypto").randomBytes(64).toString("hex"))' |\
node - |\
xargs -I{} echo "AUTH_JWT_SECRET={}" >> .docker.env
# Set MongoDB connection string
echo 'MONGO_URI=mongodb://root:root@mongo:27017' >> .docker.envOnce .docker.env is in place, run the following command to automatically build and start services:
docker compose build
docker compose up -dAfter Docker finishes this process, open http://localhost:5001 in your browser. You should see a login page with the app version in the bottom left corner.
When you are finished testing Herda and want to teardown the test environment, run the stop command to stop services:
docker compose stopℹ️ All Docker Compose actions, including rebuilding the Herda image, should continue to use both Compose files. They are automatically merged by Docker to create a complete environment.
Both the server app and PWA are configured using environment variables. These can be set in .env and web/.env respectively.
For complete configuration references, refer to:
- Server: usage of
process.env.*in src/index.ts - PWA: usage of
import.meta.env.VITE_*in web/src/build.ts
ℹ️ In development, both apps load configuration at startup (and in the case of the PWA, configuration is also hot reloaded).
When they are built, such as to a Docker image, this becomes slightly different. The server app still loads configuration at startup, but the PWA is configured at build time and cannot be reconfigured afterwards.
Accordingly, when building the PWA or Docker image, ensure the PWA is correctly configured as it cannot be changed afterwards.
See LICENSE.md