Skip to content

Jenkins

Purpose

Jenkins is the operator dashboard for this box. It provides:

  • webhook-triggered deploys for git-managed apps
  • scheduled verification and image-check jobs
  • manual backup, deploy, restart, rollback, and inspection jobs
  • a low-friction onboarding workflow for new services

The controller itself lives in /home/steam/automation/jenkins and is reverse proxied publicly at https://jenkins.ilgaming.xyz.

Private Git access

For private GitHub repos, Jenkins should authenticate over SSH rather than embedding tokens in repo URLs.

Use this pattern:

  1. Create a dedicated keypair for Jenkins, for example ssh-keygen -t ed25519 -f /home/steam/automation/jenkins/ssh/id_ed25519 -N '' -C 'jenkins@ilgaming'.
  2. Add the public key as a read-only deploy key on the repo, or to a dedicated GitHub machine user that has repo access.
  3. Create /home/steam/automation/jenkins/ssh/known_hosts with github.com in it, for example via ssh-keyscan github.com.
  4. Keep the private key mode strict on the host, typically 600 for the key and 700 for the directory.
  5. Set JENKINS_SSH_DIR in jenkins/.env if you want a non-default path.
  6. Rebuild the Jenkins container so the SSH client and mounted key material are available.
  7. Use SSH repo URLs in onboarding and managed app contracts, for example [email protected]:KPInc425/holiday-card-v2.git.

The Jenkins compose stack mounts JENKINS_SSH_DIR to /root/.ssh and exports a strict GIT_SSH_COMMAND, so both onboarding clones and later deployctl.sh fetch and pull operations use the same key and known-hosts file.

Job families

Family Meaning
deploy-* Deploy or redeploy a managed app
check-* Inspect upstream hosted-image stacks for available updates
list-* Show registry contents
status-* Show compose status for a selected app
onboard-* Add or update a managed app contract, nginx config, and deploy job
backup-* Create a fresh backup archive
verify-* Restore a backup into a throwaway container and validate it
rollback-* Revert a supported git-managed app to an older revision
restart-all-managed Recover all managed apps after host-level interruptions

Automatic jobs

These are expected to run without manual clicks:

  • check-hosted-image-updates
  • deploy-harmonious-accord
  • deploy-asa-dashboard-ui
  • deploy-kpcalorietracking
  • deploy-mybibliotheca
  • deploy-pingpal
  • deploy-neonhustle-activity
  • verify-ha-backup
  • verify-affine-backup
  • verify-kpcalorietracking-backup

Manual operational jobs

These are operator tools rather than automatic delivery paths:

  • backup-ha
  • backup-affine
  • backup-kpcalorietracking
  • deploy-affine
  • deploy-any-sync-bundle
  • deploy-keycloak
  • deploy-managed-app
  • deploy-owncast
  • deploy-searxng-docker
  • list-managed-apps
  • onboard-managed-app
  • restart-all-managed
  • rollback-mybibliotheca
  • rollback-pingpal
  • status-managed-app

Using onboard-managed-app

onboard-managed-app is not a blank freestyle job. It is a parameterized pipeline job.

In the Jenkins dashboard, the intended operator flow is:

  1. Open onboard-managed-app.
  2. Click Build with Parameters.
  3. Fill in the app details in the form.
  4. Start the build.
  5. Review the console output for any generated webhook URL or nginx notes.

If you open the job page and only look for raw pipeline code or the generic New Item flow, it is easy to miss that this job already provides a usable onboarding form.

What a per-app deploy job does

Each generated deploy job runs the same three stages:

  1. Show Contract: print the current app contract.
  2. Deploy: call /home/steam/automation/deployctl.sh deploy <app-id>.
  3. Status: print the resulting compose state.

On failure, the job also prints compose status again to leave a useful log trail in Jenkins.

NeonHustleActivity

neonhustle-activity is configured as a webhook-driven compose-build app:

  • repo: https://github.com/KPInc425/NeonHustleActivity.git
  • branch filter: main
  • health endpoint: http://127.0.0.1:8780/health
  • public hostname: neonhustle.ilgaming.xyz

The generated job name is deploy-neonhustle-activity.

Keycloak

keycloak is configured as a shared platform auth service:

  • repo: https://github.com/KPInc425/keycloak.git
  • branch: main
  • health endpoint: http://127.0.0.1:8420/health/ready
  • public hostname: keycloak.ilgaming.xyz

The generated job name is deploy-keycloak.