mirror of
https://github.com/bluewave-labs/Checkmate.git
synced 2026-01-26 11:54:11 -06:00
Merge pull request #2996 from JithendraKavala/docs/imporove-contributing-setup-instructions
docs: improve local development setup instructions in CONTRIBUTING.md
This commit is contained in:
Gorkem Cetin (BWL)
184
CONTRIBUTING.md
184
CONTRIBUTING.md
@@ -6,7 +6,7 @@ We truly appreciate all kinds of contributions — code, ideas, translations or
|
||||
|
||||
Before you start, please take a moment to read the relevant section. It helps us review and accept contributions faster, and makes the whole process smoother for everyone. 💚
|
||||
|
||||
PS: **We work closely with contributors on our [Discord channel](https://discord.com/invite/NAb6H3UTjK)**. You’ll find community members, core maintainers, and first-timers helping each other out.
|
||||
PS: **We work closely with contributors on our [Discord channel](https://discord.com/invite/NAb6H3UTjK)**. You'll find community members, core maintainers, and first-timers helping each other out.
|
||||
|
||||
---
|
||||
|
||||
@@ -32,12 +32,12 @@ PS: **We work closely with contributors on our [Discord channel](https://discord
|
||||
|
||||
### Get help or ask a question?
|
||||
|
||||
Ask anything in our [Discord server](https://discord.com/invite/NAb6H3UTjK) — we’re friendly and happy to help. [Our core contributors](https://github.com/bluewave-labs/checkmate?tab=readme-ov-file#-contributing) are active and ready to support you. You can also use [GitHub Discussions](https://github.com/bluewave-labs/Checkmate/discussions) section to ask your questions.
|
||||
Ask anything in our [Discord server](https://discord.com/invite/NAb6H3UTjK) — we're friendly and happy to help. [Our core contributors](https://github.com/bluewave-labs/checkmate?tab=readme-ov-file#-contributing) are active and ready to support you. You can also use [GitHub Discussions](https://github.com/bluewave-labs/Checkmate/discussions) section to ask your questions.
|
||||
|
||||
### Report a bug?
|
||||
|
||||
1. Search [existing issues](https://github.com/bluewave-labs/checkmate/issues).
|
||||
2. If it’s not listed, open a **new issue**.
|
||||
2. If it's not listed, open a **new issue**.
|
||||
3. Include as much detail as possible: what happened, what you expected, and steps to reproduce. Logs and screenshots help.
|
||||
|
||||
### Suggest a new feature?
|
||||
@@ -48,19 +48,181 @@ Ask anything in our [Discord server](https://discord.com/invite/NAb6H3UTjK) —
|
||||
|
||||
### Set up Checkmate locally?
|
||||
|
||||
Frontend & backend:
|
||||
#### Prerequisites
|
||||
|
||||
- Node.js (with npm)
|
||||
- Docker (for MongoDB and Redis)
|
||||
- Git
|
||||
|
||||
#### Step 1: Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bluewave-labs/Checkmate.git
|
||||
cd Checkmate
|
||||
```
|
||||
|
||||
#### Step 2: Set Up Docker Containers (MongoDB & Redis)
|
||||
|
||||
Navigate to the Docker dev directory:
|
||||
|
||||
```bash
|
||||
cd server/docker/dev
|
||||
```
|
||||
|
||||
Build the Docker images:
|
||||
|
||||
```bash
|
||||
./build_images.sh
|
||||
```
|
||||
|
||||
Run Redis container:
|
||||
|
||||
```bash
|
||||
docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis
|
||||
```
|
||||
|
||||
Run MongoDB container:
|
||||
|
||||
```bash
|
||||
docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo
|
||||
```
|
||||
|
||||
Navigate back to the root directory:
|
||||
|
||||
```bash
|
||||
cd ../../..
|
||||
```
|
||||
|
||||
#### Step 3: Set Up the Backend (Server)
|
||||
|
||||
Navigate to the server directory:
|
||||
|
||||
```bash
|
||||
cd server
|
||||
```
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Create a `.env` file in the `server` directory with the following minimum required configuration:
|
||||
|
||||
```env
|
||||
CLIENT_HOST="http://localhost:5173"
|
||||
JWT_SECRET="my_secret_key_change_this"
|
||||
DB_CONNECTION_STRING="mongodb://localhost:27017/uptime_db"
|
||||
TOKEN_TTL="99d"
|
||||
ORIGIN="localhost"
|
||||
LOG_LEVEL="debug"
|
||||
```
|
||||
|
||||
**Environment Variables Explained:**
|
||||
|
||||
- `CLIENT_HOST`: Frontend URL (default: http://localhost:5173)
|
||||
- `JWT_SECRET`: Secret key for JWT tokens (change to something secure)
|
||||
- `DB_CONNECTION_STRING`: MongoDB connection URL
|
||||
- `ORIGIN`: Origin for CORS purposes
|
||||
- `TOKEN_TTL`: Token time to live (in vercel/ms format)
|
||||
- `LOG_LEVEL`: Debug level (debug, info, warn, error)
|
||||
|
||||
Start the backend server:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
By default, the frontend expects the backend on `http://localhost:3001`. Update configs if needed.
|
||||
The server will run at `http://localhost:52345`.
|
||||
|
||||
#### Step 4: Set Up the Frontend (Client)
|
||||
|
||||
Open a new terminal window and navigate to the client directory from the root:
|
||||
|
||||
```bash
|
||||
cd client
|
||||
```
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Create a `.env` file in the `client` directory:
|
||||
|
||||
```env
|
||||
VITE_APP_API_BASE_URL="http://localhost:52345/api/v1"
|
||||
VITE_APP_LOG_LEVEL="debug"
|
||||
```
|
||||
|
||||
**Environment Variables Explained:**
|
||||
|
||||
- `VITE_APP_API_BASE_URL`: Backend API URL
|
||||
- `VITE_APP_LOG_LEVEL`: Log level (none, error, warn, debug, info)
|
||||
|
||||
Start the frontend:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The client will run at `http://localhost:5173`.
|
||||
|
||||
#### Step 5: Access the Application
|
||||
|
||||
Open your browser and navigate to:
|
||||
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **Backend API**: http://localhost:52345
|
||||
- **API Documentation**: http://localhost:52345/api-docs
|
||||
|
||||
#### Managing Docker Containers
|
||||
|
||||
Stop containers:
|
||||
|
||||
```bash
|
||||
docker stop uptime_redis uptime_database_mongo
|
||||
```
|
||||
|
||||
Start containers:
|
||||
|
||||
```bash
|
||||
docker start uptime_redis uptime_database_mongo
|
||||
```
|
||||
|
||||
Remove containers (if needed):
|
||||
|
||||
```bash
|
||||
docker rm uptime_redis uptime_database_mongo
|
||||
```
|
||||
|
||||
#### Troubleshooting
|
||||
|
||||
**Port already in use:**
|
||||
|
||||
- Check if another service is using ports 5173, 52345, 27017, or 6379
|
||||
- Stop the conflicting service or change the port in `.env` files
|
||||
|
||||
**MongoDB/Redis connection issues:**
|
||||
|
||||
- Verify containers are running: `docker ps`
|
||||
- Check container logs: `docker logs uptime_database_mongo` or `docker logs uptime_redis`
|
||||
|
||||
**Module not found errors:**
|
||||
|
||||
- Ensure you ran `npm install` in both `client` and `server` directories
|
||||
|
||||
**Need more help?**
|
||||
|
||||
- Check the [full documentation](https://docs.checkmate.so)
|
||||
- Ask on [Discord](https://discord.com/invite/NAb6H3UTjK)
|
||||
|
||||
### Start contributing code?
|
||||
|
||||
1. Pick or open an issue (check `good-first-issue`s first)
|
||||
2. (optional but highly suggested) Read a detailed structure of [Checkmate](https://deepwiki.com/bluewave-labs/Checkmate) if you would like to deep dive into the architecture.
|
||||
3. Ask to be assigned. If there is alrady someone assigned and it's been more than 7 days, you can raise the flag and ask to be assigned as well.
|
||||
3. Ask to be assigned. If there is already someone assigned and it's been more than 7 days, you can raise the flag and ask to be assigned as well.
|
||||
4. Create a branch from `develop`.
|
||||
5. Write your code.
|
||||
6. Run and test locally.
|
||||
@@ -75,6 +237,7 @@ Docs live in [checkmate-documentation](https://github.com/bluewave-labs/checkmat
|
||||
### Help with translations?
|
||||
|
||||
We use [PoEditor](https://poeditor.com) for translations. You can:
|
||||
|
||||
- [Sign up and join your language team](https://poeditor.com/join/project/lRUoGZFCsJ).
|
||||
- Translate UI strings.
|
||||
- Ask questions on Discord in the relevant #translations channel.
|
||||
@@ -84,6 +247,7 @@ Make sure all new UI strings in code use `t('key')`.
|
||||
### Submit a pull request?
|
||||
|
||||
Follow the [pull request checklist](#pull-request-checklist). Your PR should:
|
||||
|
||||
- Be focused on one issue.
|
||||
- Be tested locally.
|
||||
- Use our linting and translation rules.
|
||||
@@ -123,7 +287,6 @@ If one or more of these are missing, we may ask you to update your pull request
|
||||
|
||||
## Branching model
|
||||
|
||||
|
||||
- Code contributions should go to the `develop` branch.
|
||||
- `master` is used for stable releases.
|
||||
- Use descriptive branch names, like `fix/login-error` or `feat/add-alerts`.
|
||||
@@ -137,13 +300,10 @@ If one or more of these are missing, we may ask you to update your pull request
|
||||
|
||||
## Thank you
|
||||
|
||||
Thanks for making Checkmate better. We mean it. Whether it’s your first pull request or your 50th, we’re excited to build with you.
|
||||
Thanks for making Checkmate better. We mean it. Whether it's your first pull request or your 50th, we're excited to build with you.
|
||||
|
||||
|
||||
PS: feel free to introduce yourself on [Discord](https://discord.gg/YOUR-DISCORD-LINK) and say hi.
|
||||
PS: feel free to introduce yourself on [Discord](https://discord.gg/NAb6H3UTjK) and say hi.
|
||||
|
||||
-- Checkmate team
|
||||
|
||||
Also make sure you read the [document about how to make a good pull request](/PULLREQUESTS.md).
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user