Welcome to the MindVista wiki!

[!CAUTION] THIS WIKI IS UNDERGOING CONSTRUCTION.

Getting Started

Prerequisites

• A Unix-like operating system (e.g., macOS, Linux, or Windows with WSL)
• Node.js (see engines in package.json for version)
• Docker and Docker Compose

Steps

1. Clone the repository

2. Set up your environmental variables

cp .env.development.example .env

[!WARNING] It is crucial that .env.development.example is copied to .env and not .env.development or any other naming scheme. To avoid confusion between the various environments, any references in our documentation to .env.development should be interpreted as a reference to your local .env.

The example variables set are sufficient to get started with one exception: you are expected to generate PAYLOAD_SECRET yourself. We suggest using openssl rand -base64 32. You may leave the other variables blank or at their defaults for most development. In short, you may simply copy the example file, generate PAYLOAD_SECRET, and continue to the next step.

[!TIP] If you need access to any other variables, many of them are self-obtainable and you are expected to provide them yourself. Further information for how to obtain each variable can be found in the example env file. If you need access to variables that aren't self-obtainable, we will be happy to provide them! Email [email protected] with subject [Contributing] Requesting access to environmental variables and specify in your message which variables you need and for what reasons.

3. Install dependencies

npm install

4. Set up local development environment

# Start Docker containers and initialize services
npm run setup:dev

# Optional (recommended): Seed database and storage with example data
npm run seed:db:dev
npm run seed:storage:dev

The setup script will start PostgreSQL and LocalStack in Docker containers. You can manage these containers with standard Docker commands or refer to the script's output for common operations like viewing logs.

[!TIP] If you're using Linux and your Docker setup requires root permissions to run, you may need to postpend the -- --with-sudo flag when running setup:dev or seed:db:dev, but not for seed:storage:dev.

The local environment uses:

• PostgreSQL: Local database instance (default port 5432)
• LocalStack: S3-compatible storage for media files (default port 4566)

5. Run the dev server

npm run dev

6. Build artifacts and run preview

npm run build
npm run start

7. Testing

   1. We use Vitest for unit testing. You can run npm run test to "watch" for tests (i.e. run all test suites but watch for changes and rerun tests automatically as files are modified). For more commands, see https://vitest.dev/guide/cli. Unit tests are colocated inside the app router.
   2. We use Playwright for E2E testing. These tests will automatically be run on any PR (including drafts). You might also want to run these yourself. For more information, refer to Playwright's docs. E2E tests are located at the top level directory e2e.

[!NOTE] We are currently trying to hit 100% branch coverage. If a test does not exist for a component you have modified, please write relevant unit tests for it. This is not a PR requirement, just an ask.

8. Commit, push, and create a PR! See our Commit Guidelines.

[!CAUTION]
If you modify the database schema, you must create a migration which will be run when you create a PR. For security purposes, the migration will only be run manually by a staff member, so do not expect changes to occur immediately. We have Payload's push mode set to false for local development so you are able to test your migrations locally. This also means that you must create and run a migration to see any schema changes, even locally.

Troubleshooting

• If services aren't responding, ensure Docker is running and ports (by default, 3000, 4566, and 5432) are available
• Check Docker logs for specific service issues
• For database connection issues, ensure PostgreSQL container is healthy
• For S3 issues, verify LocalStack is running and bucket exists

---

We appreciate your contribution :)