Skip to content

Commit 443c445

Browse files
Hell1213Hell1213
authored
feat: add tmux-based development setup script (#161)
* feat: add tmux-based development setup script - Add setup.sh script to start all services in tmux session - Add stop.sh script for graceful shutdown - Add comprehensive development/README.md with setup instructions - Include prerequisite checks for Go, Node.js, npm, Docker, and tmux - Validate environment files before starting services - Auto-install dependencies if missing - Update main README.md with development setup section Fixes #155 * docs: clarify environment setup and add documentation references - Change backend/.env to ./backend/.env to avoid confusion - Add note about running backend in separate user environment - Clarify sync server startup command in service URLs - Add CCSync documentation website references in setup.sh error messages - Add documentation link for OAuth credential setup
1 parent 7fbfc96 commit 443c445

4 files changed

Lines changed: 359 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@
4545
- [Screenshots](#screenshots)
4646
- [Features](#features)
4747
- [Architecture](#architecture)
48+
- [Development Setup](#development-setup)
4849
- [Contributing](#contributing)
4950
- [License](#license)
5051

@@ -97,6 +98,28 @@ CCSync is composed of **three core modules**:
9798

9899
📖 Learn more in the [official documentation](https://its-me-abhishek.github.io/ccsync-docs/).
99100

101+
## Development Setup
102+
103+
Want to contribute or run CCSync locally? We've made it easy!
104+
105+
### Quick Start with Tmux (Recommended)
106+
107+
Run all services (backend, frontend, and sync server) in a single command:
108+
109+
```bash
110+
./development/setup.sh
111+
```
112+
113+
This will start all three services in separate tmux panes. See [development/README.md](development/README.md) for detailed setup instructions, prerequisites, and troubleshooting.
114+
115+
### Manual Setup
116+
117+
Alternatively, you can run each service separately:
118+
119+
- **Backend**: See [backend/README.md](backend/README.md)
120+
- **Frontend**: See [frontend/README.md](frontend/README.md)
121+
- **Full Stack**: Use `docker-compose up`
122+
100123
## Testing with Postman
101124

102125
1. Open **Postman**.

‎development/README.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# CCSync Development Setup
2+
3+
This directory contains scripts to automate local development setup for CCSync.
4+
5+
The `setup.sh` script starts all three services (backend, frontend, and sync server) in a single tmux session with separate panes for each service.
6+
7+
> **Note:** The backend should ideally be run in a separate user environment (preferably root user) to avoid permission issues with Taskwarrior configuration files.
8+
9+
## Prerequisites
10+
11+
Before running the setup script, ensure you have the following installed:
12+
13+
- **Go** (1.19 or higher) - [Installation Guide](https://go.dev/doc/install)
14+
- **Node.js** (16 or higher) and **npm** - [Installation Guide](https://nodejs.org/)
15+
- **Docker** and **Docker Compose** - [Installation Guide](https://docs.docker.com/get-docker/)
16+
- **tmux** - Terminal multiplexer
17+
- macOS: `brew install tmux`
18+
- Ubuntu/Debian: `sudo apt-get install tmux`
19+
- Fedora: `sudo dnf install tmux`
20+
21+
## Environment Configuration
22+
23+
The setup script requires environment files for both backend and frontend. Create these files before running the script.
24+
25+
### Backend Environment (`./backend/.env`)
26+
27+
Create a file at `./backend/.env` (relative to project root) with the following content:
28+
29+
```bash
30+
CLIENT_ID="your_google_client_id"
31+
CLIENT_SEC="your_google_client_secret"
32+
REDIRECT_URL_DEV="http://localhost:8000/auth/callback"
33+
SESSION_KEY="your_random_session_key"
34+
FRONTEND_ORIGIN_DEV="http://localhost:5173"
35+
CONTAINER_ORIGIN="http://localhost:8080/"
36+
```
37+
38+
**How to get Google OAuth credentials:**
39+
40+
For detailed instructions, refer to the [CCSync Documentation](https://its-me-abhishek.github.io/ccsync-docs/).
41+
42+
Quick steps:
43+
44+
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
45+
2. Create a new project or select an existing one
46+
3. Navigate to "APIs & Services" > "Credentials"
47+
4. Click "Create Credentials" > "OAuth 2.0 Client ID"
48+
5. Configure the OAuth consent screen if prompted
49+
6. Select "Web application" as the application type
50+
7. Add authorized redirect URI: `http://localhost:8000/auth/callback`
51+
8. Copy the Client ID and Client Secret
52+
53+
**Generate SESSION_KEY:**
54+
55+
You can generate a random session key using:
56+
57+
```bash
58+
openssl rand -base64 32
59+
```
60+
61+
### Frontend Environment (`frontend/.env`)
62+
63+
Create a file at `frontend/.env` with the following content:
64+
65+
```bash
66+
VITE_BACKEND_URL="http://localhost:8000/"
67+
VITE_FRONTEND_URL="http://localhost:5173"
68+
VITE_CONTAINER_ORIGIN="http://localhost:8080/"
69+
```
70+
71+
## Usage
72+
73+
### Starting the Development Environment
74+
75+
From the project root directory:
76+
77+
1. Make the script executable (first time only):
78+
79+
```bash
80+
chmod +x development/setup.sh
81+
```
82+
83+
2. Run the setup script:
84+
85+
```bash
86+
./development/setup.sh
87+
```
88+
89+
The script will:
90+
91+
- Verify all prerequisites are installed
92+
- Check that environment files exist
93+
- Install dependencies if needed (Go modules and npm packages)
94+
- Start all three services in a tmux session
95+
- Automatically attach you to the session
96+
97+
### Accessing the Services
98+
99+
Once running, you can access:
100+
101+
- **Frontend**: http://localhost:5173
102+
- **Backend API**: http://localhost:8000
103+
- **API Documentation**: http://localhost:8000/api/docs/index.html
104+
- **Sync Server**: http://localhost:8080 (started via `docker-compose up syncserver`)
105+
106+
### Tmux Commands
107+
108+
- **Detach from session** (keep services running): Press `Ctrl+b`, then `d`
109+
- **Reattach to session**: `tmux attach -t ccsync`
110+
- **Navigate between panes**: `Ctrl+b` then arrow keys
111+
- **Scroll in a pane**: `Ctrl+b` then `[`, use arrow keys, press `q` to exit
112+
113+
### Stopping the Development Environment
114+
115+
To stop all services and clean up:
116+
117+
1. Make the stop script executable (first time only):
118+
119+
```bash
120+
chmod +x development/stop.sh
121+
```
122+
123+
2. Run the stop script:
124+
125+
```bash
126+
./development/stop.sh
127+
```
128+
129+
This will kill the tmux session and stop all Docker containers.
130+
131+
## Troubleshooting
132+
133+
### Port Already in Use
134+
135+
If you see errors about ports already being in use:
136+
137+
```bash
138+
# Check what's using the ports
139+
lsof -i :8000 # Backend
140+
lsof -i :5173 # Frontend
141+
lsof -i :8080 # Sync Server
142+
143+
# Kill the process using the port
144+
kill -9 <PID>
145+
```
146+
147+
### Docker Not Running
148+
149+
Ensure Docker Desktop is running or start the Docker daemon:
150+
151+
```bash
152+
# macOS/Linux
153+
sudo systemctl start docker
154+
155+
# Or start Docker Desktop application
156+
```
157+
158+
### Permission Denied Errors
159+
160+
If you encounter permission errors with Taskwarrior:
161+
162+
```bash
163+
# Ensure your user has write permissions
164+
chmod 644 ~/.taskrc
165+
```
166+
167+
### Dependencies Not Installing
168+
169+
If Go modules or npm packages fail to install:
170+
171+
```bash
172+
# Backend
173+
cd backend
174+
go mod download
175+
go mod tidy
176+
177+
# Frontend
178+
cd frontend
179+
npm install
180+
```
181+
182+
### Session Already Exists
183+
184+
If the tmux session already exists, the script will attach to it. To start fresh:
185+
186+
```bash
187+
# Kill the existing session
188+
tmux kill-session -t ccsync
189+
190+
# Run setup again
191+
./development/setup.sh
192+
```
193+
194+
## Additional Resources
195+
196+
- [CCSync Documentation](https://its-me-abhishek.github.io/ccsync-docs/)
197+
- [Taskwarrior Documentation](https://taskwarrior.org/docs/)
198+
- [Tmux Cheat Sheet](https://tmuxcheatsheet.com/)
199+
- [Contributing Guidelines](../CONTRIBUTING.md)
200+
201+
## Notes
202+
203+
- The setup script automatically installs dependencies if they're not present
204+
- All services run in development mode with hot-reloading enabled
205+
- Logs from all services are visible in their respective tmux panes
206+
- The script validates environment files before starting services

‎development/setup.sh‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
#!/bin/bash
2+
3+
SESSION="ccsync"
4+
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
5+
6+
echo "CCSync Development Setup"
7+
echo "========================"
8+
echo ""
9+
10+
if ! command -v tmux &> /dev/null; then
11+
echo "Error: tmux is not installed."
12+
echo "Install it using:"
13+
echo " - macOS: brew install tmux"
14+
echo " - Ubuntu/Debian: sudo apt-get install tmux"
15+
echo " - Fedora: sudo dnf install tmux"
16+
exit 1
17+
fi
18+
19+
if ! command -v go &> /dev/null; then
20+
echo "Error: Go is not installed."
21+
echo "Download from: https://go.dev/doc/install"
22+
exit 1
23+
fi
24+
25+
if ! command -v node &> /dev/null; then
26+
echo "Error: Node.js is not installed."
27+
echo "Download from: https://nodejs.org/"
28+
exit 1
29+
fi
30+
31+
if ! command -v npm &> /dev/null; then
32+
echo "Error: npm is not installed."
33+
echo "It should come with Node.js: https://nodejs.org/"
34+
exit 1
35+
fi
36+
37+
if ! docker info &> /dev/null; then
38+
echo "Error: Docker is not running."
39+
echo "Please start Docker Desktop or the Docker daemon."
40+
exit 1
41+
fi
42+
43+
if [ ! -f "$ROOT_DIR/backend/.env" ]; then
44+
echo "Error: backend/.env file not found."
45+
echo "Please create it with required environment variables."
46+
echo "See development/README.md or https://its-me-abhishek.github.io/ccsync-docs/ for details."
47+
exit 1
48+
fi
49+
50+
if [ ! -f "$ROOT_DIR/frontend/.env" ]; then
51+
echo "Error: frontend/.env file not found."
52+
echo "Please create it with required environment variables."
53+
echo "See development/README.md or https://its-me-abhishek.github.io/ccsync-docs/ for details."
54+
exit 1
55+
fi
56+
57+
echo "Installing dependencies..."
58+
echo ""
59+
60+
cd "$ROOT_DIR/backend"
61+
if [ ! -d "vendor" ] && [ ! -f "go.sum" ]; then
62+
echo "Downloading Go modules..."
63+
go mod download
64+
go mod tidy
65+
fi
66+
67+
cd "$ROOT_DIR/frontend"
68+
if [ ! -d "node_modules" ]; then
69+
echo "Installing npm packages..."
70+
npm install
71+
fi
72+
73+
echo ""
74+
echo "Starting services in tmux session '$SESSION'..."
75+
echo ""
76+
77+
tmux has-session -t $SESSION 2>/dev/null
78+
79+
if [ $? == 0 ]; then
80+
echo "Session '$SESSION' already exists."
81+
echo "Attaching to existing session..."
82+
tmux attach -t $SESSION
83+
exit 0
84+
fi
85+
86+
tmux new-session -d -s $SESSION -n "ccsync"
87+
88+
tmux send-keys -t $SESSION:0 "cd $ROOT_DIR/backend && echo 'Starting Backend...' && go run ." C-m
89+
90+
tmux split-window -h -t $SESSION:0
91+
tmux send-keys -t $SESSION:0.1 "cd $ROOT_DIR/frontend && echo 'Starting Frontend...' && npm run dev" C-m
92+
93+
tmux split-window -v -t $SESSION:0.1
94+
tmux send-keys -t $SESSION:0.2 "cd $ROOT_DIR && echo 'Starting Sync Server...' && docker-compose up syncserver" C-m
95+
96+
tmux select-layout -t $SESSION:0 main-vertical
97+
98+
echo "Services started successfully!"
99+
echo ""
100+
echo "Tmux commands:"
101+
echo " - Detach: Ctrl+b then d"
102+
echo " - Reattach: tmux attach -t $SESSION"
103+
echo " - Kill session: tmux kill-session -t $SESSION"
104+
echo ""
105+
echo "Attaching to session..."
106+
sleep 1
107+
108+
tmux attach -t $SESSION

‎development/stop.sh‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#!/bin/bash
2+
3+
SESSION="ccsync"
4+
5+
echo "Stopping CCSync development environment..."
6+
echo ""
7+
8+
tmux has-session -t $SESSION 2>/dev/null
9+
10+
if [ $? != 0 ]; then
11+
echo "Session '$SESSION' does not exist or is not running."
12+
exit 0
13+
fi
14+
15+
echo "Killing tmux session '$SESSION'..."
16+
tmux kill-session -t $SESSION
17+
18+
echo "Stopping Docker containers..."
19+
docker-compose down
20+
21+
echo ""
22+
echo "CCSync development environment stopped successfully."

0 commit comments

Comments
 (0)