IdeaProjects Workspace: Essential Git & Shell Commands - Running reference guide

workspace-commands.md

A running reference guide of crucial commands for the IdeaProjects workspace. Last updated: 2026-09-16.

---

CI/CD Build Status & Monitoring

GitHub Actions Workflow Status

# List recent GitHub Actions workflow runs
gh run list --limit 10

# View specific run details
gh run view <run_id>

# View specific job logs from a run
gh run view <run_id> --job=<job_id> --log

Check GitHub Actions Workflow Status

# List all workflows in repository
gh workflow list

# View specific workflow details
gh workflow view <workflow_name>

Verify GHCR Image Metadata

# Check image revision and creation timestamp
docker inspect ghcr.io/sathishjayapal/runs-app:latest | grep -i "revision|created"

CI/CD Image Naming Consistency Check

Ensure IMAGE_NAME in workflow matches docker-compose reference

# GHCR: ghcr.io/${{ github.repository }} → ghcr.io/sathishjayapal/project-name
# Docker Hub: ${DOCKERHUB_USERNAME}/project-name

---

Watchtower Monitoring (Automated Container Updates)

View Watchtower Logs

# Display latest Watchtower logs with tail
docker logs sathish-stack-watchtower-1 --tail 50

Force Watchtower to Check for Updates Immediately

# Send HUP signal to trigger update check
docker kill -s HUP sathish-stack-watchtower-1

Check Container Image Details

# Inspect container creation timestamp and revision
docker inspect container_name | grep -i "created|revision"

Force Pull Latest Image from Registry

# Pull latest images to verify availability
docker pull ghcr.io/sathishjayapal/runs-app:latest
docker pull travelhelper0h/dbcleaner:latest

Verify Running Container vs Latest Image

# Compare running container creation date
docker inspect running_container_name | grep -i "created"

# Compare latest image creation date
docker inspect image_name:latest | grep -i "created"

Test if Registry Images are Public (No Auth Needed)

# Attempt to pull images without credentials
docker pull ghcr.io/sathishjayapal/runs-app:latest
docker pull travelhelper0h/sathishlogger:latest

Verify Application Health After Update

# Check application health endpoint
curl -s http://localhost:8080/actuator/health

# Verify container is running
docker ps --filter name=container_name

---

Maven Build Commands

Basic Build Operations

# Build project (skip tests for speed)
./mvnw clean package -DskipTests

# Build with tests
./mvnw verify -B

# Run tests only
./mvnw test

# Run a single test class
./mvnw test -Dtest=MyTestClass

# Run a single test method
./mvnw test -Dtest=MyTestClass#myMethod

# Format code (Spotless - eventstracker, mytracker, verbose-barnacle)
./mvnw spotless:apply

# Check formatting without applying
./mvnw spotless:check -B

# Build and test single module in multi-module project
./mvnw package -pl :module-name -am -DskipTests

# Install dependencies offline (for Docker builds)
./mvnw dependency:go-offline -B

# Clean install with local repository
./mvnw clean install -DskipTests -B

Running Applications

# Start Spring Boot app with default profile
./mvnw spring-boot:run

# Start with specific profile (dev, local, prod, etc.)
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

# Start with environment variables
set -a && source .env && set +a && ./mvnw spring-boot:run

# Start JAR file after build
java -jar target/*.jar

# Start JAR with specific profile
java -jar target/app.jar --spring.profiles.active=dev

---

Project-Specific Quick Start Commands

EventTracker

cd eventstracker

# Full startup with config server
./start-local-with-config.sh

# Start just dependencies (then run app in IDE)
./start-dependencies.sh

# Run the app
./mvnw spring-boot:run

Runs App (Spring Boot + React)

cd runs-app

# Setup Garmin SDK (run once)
./setup-garmin-sdk.sh

# Local dev setup (starts PostgreSQL container, creates .env)
./dev-up.sh

# Reset to clean state
./dev-up.sh --reset

# Backend: Spring Boot (terminal 1)
./mvnw spring-boot:run

# Frontend: React dev server (terminal 2)
npm run devserver    # Usually starts on localhost:3000 or :8081

# Build frontend during Maven build
./mvnw clean package -DskipTests

# Build and package JAR
./mvnw clean package -DskipTests -B && mv target/*.jar target/app.jar

Runs AI Analyzer

cd runs-ai-analyzer

# Setup PostgreSQL + pgvector + Ollama
./dev-up.sh

# Run the app
./mvnw spring-boot:run

# Run with VM database (if available)
vm-db-up.sh --target vm

MyTracker (Multi-module with Kafka)

cd mytracker

# Build all modules
./mvnw clean package -DskipTests

# Build single module (e.g., trackgarmin)
./mvnw package -pl :trackgarmin -am -DskipTests

# Start services (each has separate .env)
cd trackgarmin && ./dev-up.sh && ./mvnw spring-boot:run

Verbose Barnacle (React + Spring Boot)

cd verbose-barnacle

# Frontend tests
npm test

# Dev server startup
npm run devserver

# Build frontend + backend JAR
./mvnw clean package -DskipTests

---

Docker & Compose Commands

Container Operations

# Start all services defined in docker-compose.yml
docker compose up -d

# Start specific service
docker compose up -d postgres
docker compose up -d rabbitmq

# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v

# View running containers
docker compose ps

# View logs
docker compose logs -f postgres
docker compose logs -f rabbitmq

# Access container shell
docker exec -it container_name bash

# Inspect container logs with tail
docker compose logs -f --tail=100 service_name

# Start Portainer (Docker management UI)
docker run -d --name=portainer --restart=always \
  -p 8000:8000 -p 9000:9000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce

Database Containers

# PostgreSQL from shared infrastructure
# All project databases run through: jubilant-memory/config/docker-compose.yml
docker compose -f jubilant-memory/config/docker-compose.yml up -d postgres

# View database status
docker compose ps postgres

# Access PostgreSQL shell
docker exec -it postgres psql -U postgres -d postgres

# Multi-project orchestration
consolidated-postgres/scripts/local/multi-dev-up.sh
./consolidated-postgres/diagnose.sh

---

Prometheus Installation & Setup

Credit: Setup commands based on aussiearef/Prometheus repository

Prerequisites & System User Setup

# Create system user group for prometheus (security isolation)
sudo groupadd --system prometheus

# Create system user for prometheus with no login shell (security best practice)
sudo useradd -s /sbin/nologin --system -g prometheus prometheus

# Create Prometheus data directory (stores time-series metrics)
sudo mkdir /var/lib/prometheus

# Create directory for alert rules (Prometheus alerting configuration)
mkdir -p /etc/prometheus/rules

# Create directory for alert rules (Prometheus alerting configuration)
sudo mkdir -p /etc/prometheus/rules

# Create additional rules directory (for modular alert rule files)
sudo mkdir -p /etc/prometheus/rules.s

# Create service discovery directory (for dynamic target discovery configuration)
sudo mkdir -p /etc/prometheus/files_sd

Download & Install Binaries

# Download Prometheus v3.14.0 release (latest stable binary for Linux amd64 architecture)
sudo wget https://github.com/prometheus/prometheus/releases/download/v3.14.0/prometheus-3.14.0.linux-amd64.tar.gz

# Extract downloaded tarball (unpack Prometheus and Promtool binaries)
tar xvf prometheus-3.14.0.linux-amd64.tar.gz

# Navigate to extracted directory (where binaries are located)
cd prometheus-3.14.0.linux-amd64/

# Install Prometheus and Promtool binaries to system PATH (makes them globally available)
sudo mv prometheus promtool /usr/local/bin

# Install Prometheus and Promtool binaries to system PATH (makes them globally available)
sudo mv prometheus promtool /usr/local/bin

# Verify Prometheus installation and check version (confirms successful binary installation)
prometheus --version

Configuration & Permissions

# Move default configuration to system config directory (establishes standard config location)
sudo mv prometheus.yml /etc/prometheus/prometheus.yml

# Download systemd service file (enables Prometheus to run as a managed system service)
# Source: https://raw.githubusercontent.com/aussiearef/Prometheus/refs/heads/main/prometheus.service
# Save to: /etc/systemd/system/prometheus.service

# Set Prometheus user as owner of config directory (allows service to read configurations)
sudo chown -R prometheus:prometheus /etc/prometheus

# Set Prometheus user as owner of all config files (security permission management)
sudo chown -R prometheus:prometheus /etc/prometheus/*

# Set directory permissions for config access (755 = rwxr-xr-x for user, r-x for group/others)
sudo chmod -R 775 /etc/prometheus/*

# Set Prometheus user as owner of data directory (allows service to write metrics)
sudo chown -R prometheus:prometheus /var/lib/prometheus

Start & Manage Service

# Reload systemd daemon (registers new or updated service files)
sudo systemctl daemon-reload

# Start Prometheus service (begins collecting and storing metrics)
sudo systemctl start prometheus

# Check Prometheus service status (verify it's running without errors)
systemctl status prometheus

---

Git Commands

Branch Operations

# Check current branch and status
git status

# Create and switch to new branch
git checkout -b feature/my-feature

# Switch to existing branch
git checkout main
git checkout develop

# List all branches (local)
git branch -a

# Delete local branch
git branch -d branch_name

# Delete remote branch
git push origin --delete branch_name

# Rename current branch
git branch -m new-name

Commit & History

# View commit history
git log

# View commits with author and time
git log --oneline --decorate

# View commits for specific file
git log -- path/to/file

# View changes in specific commit
git show commit_hash

# View diff between branches
git diff main..feature/my-feature

Staging & Committing

# Stage specific file
git add path/to/file

# Stage all changes
git add .

# Stage all files (including untracked)
git add -A

# Unstage file
git reset HEAD path/to/file

# Commit with message
git commit -m "your message"

# Commit with attribution (Claude Code workflow)
git commit -m "Your message

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>"

# Amend previous commit
git commit --amend

# Amend without changing message
git commit --amend --no-edit

Pushing & Pulling

# Fetch latest from remote
git fetch origin

# Pull latest changes
git pull origin main

# Push to remote
git push origin feature/my-feature

# Push with tracking (new branch)
git push -u origin feature/my-feature

# Push all branches
git push origin --all

Stashing & Cleaning

# Stash current changes
git stash

# Stash with message
git stash save "work in progress"

# List stashes
git stash list

# Apply most recent stash
git stash pop

# Apply specific stash
git stash apply stash@{0}

# Remove untracked files
git clean -fd

# Stash untracked files too
git stash -u

---

PostgreSQL & Database Commands

Local Database Access

# Connect to local PostgreSQL (via docker container)
docker exec -it postgres psql -U postgres

# Connect to specific database
psql -h localhost -p 5443 -U postgres -d runs_app_local

# List databases
\l

# Switch database
\c database_name

# List tables
\dt

# View table structure
\d+ table_name

# Run SQL query
SELECT * FROM table_name LIMIT 10;

# View migrations (Flyway)
SELECT * FROM flyway_schema_history;

# Exit psql
\q

Database Reset

# Reset via dev-up.sh
cd project_name && ./dev-up.sh --reset

# Manual reset: drop and recreate database
docker compose down -v
docker compose up -d postgres
# Wait for postgres to start, then:
docker compose up service_name  # Runs migrations via Flyway

---

API Testing (Bruno / cURL)

cURL File Upload

# POST file to endpoint
curl -X POST \
  -F "file=@/path/to/file.csv" \
  http://localhost:8080/api/upload

# POST with authentication
curl -X POST \
  -H "Authorization: Bearer token" \
  -F "file=@file.csv" \
  http://localhost:8080/api/upload

# View response with headers
curl -i http://localhost:8080/api/endpoint

Bruno API Testing

• Collections stored in: bruno/ directory
• Test collections for REST/GraphQL endpoints
• VS Code extension: Install Bruno for .bru file support

---

Port Reference

Project / Service	App Port	DB Port	Notes
runs-app	8080	5443	React frontend on :3000
runs-ai-analyzer	8081	5444	pgvector; Ollama on :11434
eventstracker	9081	6433	Config server on :8888
sathishai	8080	5463
mytracker	8080	5440
sathishlogger	8080	8432
sathishproject-config-server	8888	—	Git-backed Spring Cloud Config
RabbitMQ	—	—	5672 (AMQP), 15672 (UI)
Ollama	—	—	11434 (runs-ai-analyzer)
Portainer	9000	—	Docker management UI
Prometheus	9090	—	Metrics collection & visualization

---

Environment Variables & Configuration

Setting up .env files

# Most projects generate .env via dev-up.sh
cd project_name && ./dev-up.sh

# Manually load .env before running
set -a && source .env && set +a
./mvnw spring-boot:run

# Check .env location
cat .env.example  # See template

# Common variables
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5443/dbname
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=password
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672

Config Server (eventstracker, mytracker)

# Config server VM: 192.168.4.39:8888
# Requires Git credentials in .env

# Verify config server is running
curl http://192.168.4.39:8888/health

# View application config
curl http://192.168.4.39:8888/eventstracker/local

---

Troubleshooting Commands

Common Issues

# Check if port is in use
lsof -i :8080
lsof -i :5672  # RabbitMQ

# Kill process on port
kill -9 <PID>

# View logs in container
docker compose logs -f postgres
docker compose logs -f rabbitmq

# Verify Docker Compose syntax
docker compose config

# Rebuild without cache
docker compose build --no-cache

# Check Java version
java -version

# View Maven version
./mvnw -v

# Verify Git configuration
git config --list

Database Role Issues

# If getting "password auth failed for role_name"
# Via Portainer, exec into postgres container:
ALTER ROLE runsai_local WITH PASSWORD 'newpassword';

# Or via CLI:
docker exec -it postgres psql -U postgres -c "ALTER ROLE username WITH PASSWORD 'password';"

Prometheus Troubleshooting

# Check if Prometheus is running
systemctl status prometheus

# View Prometheus logs (system journal)
journalctl -u prometheus -f

# Verify Prometheus configuration syntax
prometheus --config.file=/etc/prometheus/prometheus.yml --dry-run

# Check Prometheus port accessibility
curl -s http://localhost:9090/-/healthy

# View Prometheus targets and their status
curl -s http://localhost:9090/api/v1/targets | jq '.data'

---

Useful Aliases & Functions

Add to ~/.zshrc or ~/.bashrc:

# Maven quick commands
alias mvnw='./mvnw'
alias mvn-build='./mvnw clean package -DskipTests'
alias mvn-test='./mvnw test'
alias mvn-run='./mvnw spring-boot:run'

# Docker shortcuts
alias dc='docker compose'
alias dc-up='docker compose up -d'
alias dc-down='docker compose down'
alias dc-logs='docker compose logs -f'

# Git shortcuts
alias gs='git status'
alias ga='git add'
alias gc='git commit -m'
alias gp='git push'
alias gl='git log --oneline -10'

# Project navigation
alias runs='cd ~/IdeaProjects/runs-app'
alias events='cd ~/IdeaProjects/eventstracker'
alias mytrack='cd ~/IdeaProjects/mytracker'

---

Key Files & Documentation

• Main workspace instructions: CLAUDE.md (at IdeaProjects root)
• Build scripts: Each project has dev-up.sh for local setup
• Shared infrastructure: jubilant-memory/config/docker-compose.yml
• API collections: bruno/ directory (.bru files)
• Multi-project orchestration: consolidated-postgres/
• Workspace documentation: Root level *.md files (DATABASE_SETUP.md, etc.)

---

Important Notes

RabbitMQ Cross-Service Messaging

When publishing to a queue consumed by a different service, use rabbitTemplate.send() with MessageBuilder, NOT convertAndSend():

byte[] body = objectMapper.writeValueAsString(event).getBytes(StandardCharsets.UTF_8);
Message message = MessageBuilder.withBody(body)
        .setContentType("application/json")
        .setContentEncoding(StandardCharsets.UTF_8.name())
        .build();
rabbitTemplate.send(exchange, routingKey, message);   // send(), NOT convertAndSend()

See runs-app: GarminCsvImportService.publishGarminEvent for reference implementation.

Global Git Email

Pre-configured for noreply GitHub:

203055+sathishjayapal@users.noreply.github.com

Java Version

Projects use Java 21 and Spring Boot 3.x–4.x

---

Updates & Learning

This GIST is a living reference. Check for updates and add new commands as you discover them.

Last command additions:

• Prometheus installation & startup commands (from aussiearef/Prometheus)
• Prometheus troubleshooting section
• CI/CD section restructured with subsections
• Watchtower monitoring section restructured with subsections
• Maven profile startup commands
• PostgreSQL role management for CI/CD issues
• Portainer container access patterns