Troubleshooting

Common issues, symptoms, and fixes encountered with Friendly Jenkins.

Port Conflicts

Symptom: listen tcp … bind: address already in use (e.g., MySQL 3306).
Fix: change service port in .env (e.g., MYSQL_PORT=3307) or stop the conflicting container.

Pipelines probe ports with ss / netstat / lsof; install at least one of them. Example (Debian/Ubuntu):

sudo apt-get update && sudo apt-get install -y iproute2 net-tools lsof

RHEL/CentOS:

sudo yum install -y iproute net-tools lsof

Volume Permission Errors

Symptom: Operation not permitted when changing ownership under /opt/qa-envs/<env>/volumes/.
Fix: sudo chown -R 1000:1000 /opt/qa-envs/<env>/volumes/ on the agent.

Missing Environment Variables

Symptom: Error: <VAR> is not set.

Fix: append the variable to <service>.env or .env, then redeploy:

echo "MYSQL_ROOT_PASSWORD=password123" >> mysql.env
docker compose up -d

Health Checks Failing

Symptom: docker compose ps shows Up (unhealthy).
Fix:
- Increase timeouts/retries:

healthcheck:
  test: ["CMD", "mysqladmin", "ping"]
  interval: 10s
  timeout: 10s
  retries: 5
  start_period: 60s

Use CMD-SHELL when env expansion is needed:

test: ["CMD-SHELL", "mysql -u $$MYSQL_USER -p$$MYSQL_PASSWORD -e 'SELECT 1'"]

Shared Library Not Loading

Symptom: MissingMethodException: No such DSL method 'createEnvStep'.
Fix:
- Verify Global Pipeline Library points to the correct Git URL and credentials.
- Manually sync library if needed:

cd shared-library && git pull
docker cp vars/ jenkins-qa-master:/var/jenkins_home/qa-library/

Confirm webhook secret matches WEBHOOK_SECRET_EXPECTED.

Webhook Not Firing Sync

Ensure URL token matches Jenkins job token.
X-Gitlab-Token header must equal configured secret.
Branch/tag must match allowed regex (commonly main or version tags).

Recovering Deleted Environments

If backups exist on master: restore tarball into /var/jenkins_home/qa-data/envs/ then redeploy.
If not: re-create the environment from templates; Docker volumes may remain if only “Stop” was used.