Jenkins

Launch the AMI from AWS Marketplace:

• Open AWS Marketplace and search for "Jenkins SecureAnyCloud".
• Click Continue to Subscribe, accept the terms, then click Continue to Configuration.
• Select your Region and Software Version.
• Click Continue to Launch.
• Choose Launch through EC2 for full control over instance configuration.
• Select your instance type (t3.medium is recommended).
• Configure storage with a minimum of 20 GB gp3. Use 50 GB for active build environments.
• Configure your Security Group with the inbound rules listed below.
• Select your EC2 key pair and launch the instance.

Inbound rules for the security group:

• Port 22, TCP, source: your IP. Purpose: SSH access.
• Port 8080, TCP, source: your IP. Purpose: Jenkins web interface.

Important: Restrict port 8080 to trusted IP addresses. Do not open the Jenkins web interface to 0.0.0.0/0 unless you have configured authentication and are using HTTPS.

When your instance is running and has passed both status checks (2/2), connect over SSH:

ssh -i your-key.pem ec2-user@<public-ip-address>

Replace your-key.pem with the path to your EC2 key pair and <public-ip-address> with the public IP of your instance.

Important: Wait until the instance reaches 2/2 successful status checks before you connect. If you connect too early, you may see an error such as:

Permission denied (publickey,gssapi-keyex,gssapi-with-mic).

This is expected during the initial boot. Wait for both status checks to pass, then try again.

To switch to the root user, run:

sudo su -

The Jenkins service starts automatically on boot. Open the Jenkins web interface in your browser:

http://<public-ip-address>:8080

The Unlock Jenkins screen appears. Retrieve the initial administrator password from the instance:

cat /var/lib/jenkins/secrets/initialAdminPassword

The output looks like this example:

7d3a6676bf72419bb4d00f6143a456a7

Copy the password, paste it into the Administrator password field in your browser, then click Continue.

After you unlock Jenkins, the Customize Jenkins screen offers two options:

• Install suggested plugins is recommended for most use cases. It installs commonly used plugins, including Git, Pipeline and other essentials.
• Select plugins to install lets you choose your own plugins.

Click the option you prefer. Installation can take 30 to 60 seconds, depending on your instance type and network speed. The screen may appear blank for a moment during installation, which is normal.

When plugin installation completes, the Create First Admin User screen appears. Complete the form:

• Enter a Username for your admin account.
• Set a strong Password and confirm it.
• Enter your Full name and Email address.
• Click Save and Continue.

The Instance Configuration screen shows the Jenkins URL. Set it to the URL where your users will access Jenkins. The default is the current IP address and port.

For production use, consider setting it to your DNS hostname, for example http://jenkins.yourdomain.com:8080.

Click Save and Finish, then click Start using Jenkins. Jenkins is now ready to use.

Sign in to the AWS Management Console, open the EC2 service and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Jenkins LTS. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, then create or select a security group that allows inbound port 22 from your management network and inbound port 80 from the trusted networks that will reach Jenkins. Do not open port 80 to the public internet until you have configured TLS (see the HTTPS step).

Select Launch instance. First-boot initialization takes approximately one to two minutes after the instance state becomes Running and the status checks pass.

Run the following command to launch an instance from the SecureAnyCloud Jenkins LTS Marketplace AMI into an existing subnet and security group.

Replace <ami-id> with the AMI ID shown on the Marketplace listing and <key-name> with your EC2 key pair name. Replace <subnet-id> with your subnet ID and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=jenkins-01}]'

On success, the command prints a JSON document. Note the instance ID. When the instance is running, retrieve its public address with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

• Jenkins LTS 2 on Ubuntu 24.04: login user ubuntu

The first-boot service runs after the SSH daemon becomes ready. The credentials file is in place within about a minute of the instance entering the Running state. Wait for the file to appear before you sign in to the web interface.

ssh <login-user>@<public-ip>
sudo cat /root/jenkins-credentials.txt

The plain text file contains the Jenkins URL, the administrator username (admin) and the administrator password. Copy these values to a secure location, such as a password manager or an encrypted vault. Do not commit them to source control.

Every command block in this guide that calls the Jenkins HTTP API begins by reading the administrator password from the credentials file into a PASSWORD shell variable, so each block is self-contained:

PASSWORD="$(sudo awk -F= '/^JENKINS_ADMIN_PASSWORD=/ {print $2}' /root/jenkins-credentials.txt)" echo "admin password length: ${#PASSWORD}"

Jenkins exposes an unauthenticated /login page, which confirms that the controller and the nginx reverse proxy are both healthy. It also exposes the authenticated /api/json endpoint, which confirms that the administrator user can sign in:

PASSWORD="$(sudo awk -F= '/^JENKINS_ADMIN_PASSWORD=/ {print $2}' /root/jenkins-credentials.txt)" curl -s -o /dev/null -w "login HTTP: %{http_code}\n" http://127.0.0.1/login curl -s -o /dev/null -w "api HTTP: %{http_code}\n" -u "admin:$PASSWORD" http://127.0.0.1/api/json

Both responses return HTTP: 200. The /api/json endpoint also returns a JSON document that describes the controller. With jq installed, you can inspect the Jenkins version, the number of executors and the mode:

PASSWORD="$(sudo awk -F= '/^JENKINS_ADMIN_PASSWORD=/ {print $2}' /root/jenkins-credentials.txt)" curl -s -u "admin:$PASSWORD" http://127.0.0.1/api/json | jq '{numExecutors, mode, useSecurity, version: ._class}'

The image contains these components, listed with their version and source:

• Jenkins LTS 2.5xx.x from pkg.jenkins.io/debian-stable
• OpenJDK 21 headless from Ubuntu noble main
• nginx 1.24 from Ubuntu noble main
• Ubuntu 24.04 LTS, the SecureAnyCloud golden base image
• SecureAnyCloud overrides: sac-overrides.conf and sac-init.groovy, included in the image

The image has no second backend database, no message broker and no second exposed port. Authentication uses the built-in Jenkins user database, and the controller stores all of its state under /var/lib/jenkins.

The Jenkins working directory is JENKINS_HOME at /var/lib/jenkins. It lives on a dedicated EBS volume, so you can resize it independently of the root volume. The main directories and files in the image are:

• /usr/share/java/jenkins.war: the Jenkins controller WAR file from the APT package
• /etc/systemd/system/jenkins.service.d/sac-overrides.conf: the SecureAnyCloud systemd drop-in, which binds 127.0.0.1:8080 and disables the setup wizard
• /etc/nginx/sites-available/jenkins: the nginx reverse proxy configuration
• /var/lib/jenkins/: JENKINS_HOME, on the dedicated data volume (job configs, build history, plugins and workspaces)
• /var/lib/jenkins/init.groovy.d/sac-init.groovy: the Groovy init script that provisions the admin user from /etc/jenkins/admin-password.txt
• /etc/jenkins/admin-password.txt: the per-instance admin password file, mode 0640 root:jenkins
• /etc/jenkins/jenkins-url.txt: the Jenkins URL captured at first boot
• /var/log/jenkins/jenkins.log: the Jenkins controller log
• /root/jenkins-credentials.txt: the per-instance administrator password, mode 0600, root only

Jenkins runs as the systemd service jenkins.service, fronted by nginx.service. The first-boot unit is jenkins-firstboot.service. It is skipped on every boot after the first because its sentinel file is /var/lib/sac/data/jenkins-firstboot.done. Manage the main services with systemctl:

sudo systemctl status --no-pager jenkins
sudo systemctl is-active jenkins
sudo systemctl is-active nginx

After you edit the configuration, restart the controller:

sudo systemctl restart jenkins

Jenkins runs as the jenkins system user, which owns /var/lib/jenkins. Jenkins writes its log to /var/log/jenkins/jenkins.log. You can also read the log in the journal with sudo journalctl -u jenkins -n 200 --no-pager.

nginx fronts Jenkins on TCP port 80. After you open port 80 to your management network in the security group, open this URL in your browser:

http://<public-ip>/

Jenkins shows a sign-in page. Enter the administrator username (admin) and the administrator password from /root/jenkins-credentials.txt.

After you sign in, Jenkins shows the dashboard. A freshly launched instance has no jobs, so the dashboard offers the Create a job shortcut, links to set up a distributed build and the New Item action in the top-left navigation. The footer shows the Jenkins version.

The New Item form lets you choose a freestyle project, a pipeline, a multibranch pipeline or a folder. Enter a name, pick a type and select OK to open the job configuration form.

The Manage Jenkins section covers system configuration, plugin management, user management, credential storage, build tools, agents and clouds. The screenshot below shows the System configuration page.

Jenkins exposes both a web interface and a REST API. Anything you can do in the web interface, you can also do with curl, the Jenkins CLI or one of the language SDKs.

Every Jenkins write is either a web form POST or an XML config POST. The following block creates a freestyle job named hello-world that prints a message, then triggers a build:

PASSWORD="$(sudo awk -F= '/^JENKINS_ADMIN_PASSWORD=/ {print $2}' /root/jenkins-credentials.txt)" CRUMB="$(curl -s -u admin:$PASSWORD 'http://127.0.0.1/crumbIssuer/api/json' | jq -r '.crumbRequestField + ":" + .crumb')" cat > /tmp/hello-world.xml <<'XML' <?xml version='1.1' encoding='UTF-8'?> <project> <description>sac smoke job</description> <keepDependencies>false</keepDependencies> <properties/> <scm class="hudson.scm.NullSCM"/> <canRoam>true</canRoam> <disabled>false</disabled> <builders> <hudson.tasks.Shell> <command>echo "Hello from Jenkins on $(hostname)"</command> </hudson.tasks.Shell> </builders> <publishers/> <buildWrappers/> </project> XML curl -s -u admin:$PASSWORD -H "$CRUMB" \
  -H 'Content-Type: application/xml' --data-binary @/tmp/hello-world.xml \
  'http://127.0.0.1/createItem?name=hello-world' curl -s -o /dev/null -w "create HTTP: %{http_code}\n" -u admin:$PASSWORD \
  'http://127.0.0.1/job/hello-world/api/json' curl -s -o /dev/null -w "trigger HTTP: %{http_code}\n" -u admin:$PASSWORD -H "$CRUMB" \
  -X POST 'http://127.0.0.1/job/hello-world/build'

The job appears on the Jenkins dashboard. The commands run in this order:

• The first call creates the job. It prints no body on success.
• The second call confirms that the /api/json endpoint of the job returns 200.
• The third call triggers a build, which Jenkins queues for the next available executor.

To inspect the build log, open http://<public-ip>/job/hello-world/, select the latest build and choose Console Output.

The default Jenkins install includes only the minimum plugins needed to boot the controller. Most deployments add the Pipeline, Git, Credentials and Workflow plugins, plus any plugins specific to your build agents and your SCM provider.

To install plugins from the web interface, open Manage Jenkins -> Plugins -> Available plugins. Search for the plugins you need, select their checkboxes and select Install. Jenkins downloads each plugin, resolves its dependencies and applies the plugins on the next restart.

You can also script plugin installation with the Jenkins CLI or the REST API. Once Jenkins is running, the Jenkins CLI is available as a jar at http://<public-ip>/jnlpJars/jenkins-cli.jar:

sudo apt-get install -y openjdk-21-jre-headless curl -sO http://<public-ip>/jnlpJars/jenkins-cli.jar java -jar jenkins-cli.jar -s http://<public-ip>/ -auth admin:<password> install-plugin workflow-aggregator git credentials -deploy java -jar jenkins-cli.jar -s http://<public-ip>/ -auth admin:<password> safe-restart

For declarative pipelines, the Pipeline: Multibranch and Pipeline: GitHub Branch Source plugins are the most commonly added pair.

Individual developers should not use the administrator account. Create a separate account for each developer under Manage Jenkins -> Users -> Create User.

The default authorization strategy is Logged-in users can do anything, so every signed-in user has full control. For finer-grained control, install the Role-based Authorization Strategy plugin and assign roles per project or per folder under Manage Jenkins -> Manage and Assign Roles.

To create a user programmatically from the CLI, run:

PASSWORD="$(sudo awk -F= '/^JENKINS_ADMIN_PASSWORD=/ {print $2}' /root/jenkins-credentials.txt)" echo 'jenkins.model.Jenkins.instance.securityRealm.createAccount("alice", "change-me-in-your-secrets-manager")' \
  | java -jar /var/cache/jenkins/war/WEB-INF/lib/cli-*.jar -s http://127.0.0.1/ -auth admin:$PASSWORD groovy =

The Groovy script runs inside the controller and adds the user to the built-in user database immediately.

For a production deployment, rotate the administrator password that was generated on first boot. The image reads the password file every time Jenkins starts, so rotation is simple. Write a new value and restart Jenkins, and the Groovy init script updates the stored password of the admin user.

NEW_PASSWORD="$(head -c 32 /dev/urandom | base64 | tr -d '/+=' | head -c 24)" echo "$NEW_PASSWORD" | sudo tee /etc/jenkins/admin-password.txt > /dev/null
sudo chown root:jenkins /etc/jenkins/admin-password.txt
sudo chmod 0640 /etc/jenkins/admin-password.txt
sudo sed -i "s|^JENKINS_ADMIN_PASSWORD=.*|JENKINS_ADMIN_PASSWORD=$NEW_PASSWORD|" /root/jenkins-credentials.txt
sudo systemctl restart jenkins

Sign in again with the new password to confirm the rotation took effect. Store the new value in your secrets manager immediately.

By default, Jenkins runs on a single controller. For real workloads, move build execution off the controller onto distributed agents. A static agent connects to the controller over the JNLP protocol on a fixed TCP port. An inbound agent connects out from the agent host to the /wsagents/ websocket endpoint of the controller, which the nginx configuration in this image already forwards.

The simplest production pattern is the inbound agent over websocket. On the controller, create a node under Manage Jenkins -> Nodes -> New Node. Choose Permanent Agent and select Launch agent by connecting it to the controller. Jenkins generates a one-line command that you run on the agent host:

java -jar agent.jar -url http://<public-ip>/ -webSocket -secret <secret> -name <agent-name> -workDir /var/jenkins-agent

The agent registers with the controller, picks up labels and starts accepting builds. To restrict a job to the agent host, tag it with agent { label '<agent-name>' }.

This image already provides nginx in front of Jenkins. For any deployment that carries customer traffic, terminate TLS in the nginx server block so credentials and webhook payloads are not sent in clear text. nginx with a Let's Encrypt certificate gives you HTTPS without changes to the Jenkins configuration.

The following steps assume that a DNS record points your fully qualified domain name at the public IP address of the instance.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d jenkins.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

certbot rewrites /etc/nginx/sites-available/jenkins to listen on TCP 443 and redirect HTTP to HTTPS. Then restart Jenkins so that it picks up its new public URL:

echo "https://jenkins.your-domain.example/" | sudo tee /etc/jenkins/jenkins-url.txt > /dev/null
sudo systemctl restart jenkins

Customer applications and webhook providers then connect to https://jenkins.your-domain.example, and the proxy forwards requests to Jenkins on localhost. In the security group, limit port 80 to redirect-only traffic from the public internet, and limit port 443 to the trusted networks that need to reach Jenkins.

Jenkins keeps all of its data under /var/lib/jenkins on the dedicated data volume. Job configs are in jobs/<name>/config.xml, build history is under jobs/<name>/builds/, plugins are under plugins/ and the user database is under users/. For a point-in-time consistent backup, stop the service, archive or snapshot the data, and start the service again:

sudo systemctl stop jenkins
sudo tar -czf /var/backups/jenkins-home-$(date +%F).tgz -C /var/lib/jenkins .
sudo systemctl start jenkins

Copy the archive to an Amazon S3 bucket or another object store. For larger Jenkins controllers, take an Amazon EBS snapshot of the /var/lib/jenkins volume instead. A snapshot is faster, and it does not require a service stop if your workload tolerates a crash-consistent snapshot.

Ubuntu unattended-upgrades is enabled by default, so security patches for the kernel and packages apply automatically. To update Jenkins itself, run sudo apt-get update && sudo apt-get install --only-upgrade jenkins, then restart the service. Read the Jenkins LTS upgrade notes before you apply a major version jump.

This image is a single-controller Jenkins. For larger deployments:

• Grow the /var/lib/jenkins EBS volume and extend the filesystem when build history and workspaces outgrow the initial disk.
• Move build execution off the controller onto distributed agents (see step 13), and keep the controller for orchestration only.
• Put the controller behind an Application Load Balancer with TLS termination, and restrict port 80 in the security group to the load balancer and the management network.
• Consider Jenkins Operations Center or a managed Jenkins offering for fleets of controllers.
• Take regular snapshots of JENKINS_HOME and document the restore drill in your runbook.

The official Jenkins documentation at https://www.jenkins.io/doc/ covers cluster setup, the configuration as code plugin and pipeline authoring in detail.

Jenkins can run arbitrary code on the controller and on every agent it connects to. Before the instance takes customer traffic, apply these recommendations:

• Never expose port 80 to the public internet without TLS. Configure HTTPS with Let's Encrypt (step 14) and restrict port 80 to redirect-only traffic.
• Rotate the administrator password as described in step 12, and store the new value in your secrets manager.
• Create individual user accounts for every developer, and stop using the administrator account for routine work. Use the Role-based Authorization Strategy plugin for fine-grained access control.
• Restrict the security group so that ports 80 and 443 are reachable only from your trusted networks and webhook providers.
• Run builds on distributed agents, not on the built-in node of the controller. The image keeps the built-in node as the default executor for convenience. In production, label it master and reserve it for orchestration only.
• Keep plugins up to date. Plugin vulnerabilities are the most common Jenkins attack surface. The Manage Jenkins -> Plugins -> Updates tab lists every plugin with a pending update.
• Back up /var/lib/jenkins regularly and test your restores.