Skip to content

Appcircle Server Cloud Marketplaces — Image Build

This document describes how Appcircle Server machine images are built for multiple cloud providers using HashiCorp Packer. The pipeline is maintained in the server-image-packer repository and produces consistent, ready-to-run images for AWS, Azure, and Google Cloud from a single golden image definition.

Purpose

  • Build cloud VM images that already have Appcircle Server and its dependencies installed.
  • Standardize the same base OS, Docker setup, and Appcircle installation across AWS, Azure, and GCP.
  • Automate image creation so new versions (e.g. Appcircle Server updates) can be built and published without manual per-cloud steps.
  • Support multi-cloud from one codebase: one Packer template, one set of provisioner scripts, multiple cloud outputs.

For what Packer is and why we use it, see ADR-0009: Use HashiCorp Packer for Appcircle Server Cloud Marketplace Images.

What the Pipeline Does

Base images

We start from Ubuntu 22.04 LTS on each cloud:

  • AWS – Canonical’s ubuntu-jammy-22.04-amd64-server-* AMI.
  • Azure – Canonical’s 0001-com-ubuntu-server-jammy (22_04-lts).
  • GCP – ubuntu-2204-lts from the ubuntu-os-cloud project.

Single provisioner

The same script runs on every build: setup-server.sh. It:

  • Updates the system and installs dependencies (e.g. curl, unzip).
  • Installs Docker.
  • Downloads and installs the Appcircle self-hosted server package.
  • Runs the Appcircle install flow, exports a sample project, and pulls container images.
  • Configures swap and any other required setup.

Output

Packer produces one image per enabled builder, for example:

  • AWS – AMI named like appcircle-server-v3.29.8.
  • Azure – Managed image in the specified resource group.
  • GCP – Custom image in the project (e.g. appcircle-server-v3-29-8).

Version and naming

Appcircle Server version and image naming are controlled by locals in build.pkr.hcl (e.g. appcircleServerVersion, appcircleServerVVersion, appcircleServerVVersionWithDash). Updating those and re-running Packer produces new images with the new version in the name.

Installing Packer

Packer is not bundled in the repo; you need to install it on your machine.

After installation, ensure packer is on your PATH and run:

packer version

How to Use the Project

1. Clone and enter the Packer directory

git clone <this-repo>
cd server-image-packer/packer

2. Install required Packer plugins

From the packer directory:

packer init .

This downloads the plugins defined in the packer block (amazon, azure, googlecompute).

3. Configure variables and authentication

Variables are defined in variables.pkr.hcl and can be set via environment variables or -var / -var-file.

AWS

  • Set credentials (e.g. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or use IAM roles/SSM).
  • Optional: PKR_VAR_aws_region (default: us-east-1).

Azure

  • ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_SUBSCRIPTION_ID
  • TF_VAR_azure_resource_group (or variable azure_resource_group)
  • Optional: PKR_VAR_azure_region (default: eastus).

Google Cloud

  • Authenticate with GCP (e.g. gcloud auth application-default login or GOOGLE_APPLICATION_CREDENTIALS).
  • Set project: PKR_VAR_gcp_project_id (or default in variables, e.g. dev-appcircle).
  • Optional: PKR_VAR_gcp_zone (default: us-central1-a).

4. Choose what to build

In build.pkr.hcl, the build block lists which sources are active. You can:

  • Build everything (all uncommented sources):
packer build .
  • Build only one cloud using -only:
packer build -only=amazon-ebs.ubuntu-lts .
packer build -only=azure-arm.ubuntu-lts .
packer build -only=googlecompute.ubuntu-2204-lts .

Comment or uncomment the corresponding source "source.*" blocks in the build block to enable or disable clouds without changing the builder definitions.

5. Validate before building

packer validate .

Project Layout

server-image-packer/
├── README.md                 # Overview and usage
├── packer/
│   ├── build.pkr.hcl         # Packer config: plugins, builders, build block, provisioners
│   ├── variables.pkr.hcl     # Input variables (regions, project id, credentials via env)
│   └── setup-server.sh       # Provisioner script: Docker + Appcircle Server install

Updating Appcircle Server Version

  1. Edit packer/build.pkr.hcl and update the appcircleServerVersion (and related locals if you use custom naming).
  2. Run packer init . if you haven’t already or after changing plugins.
  3. Run packer build . (or -only=... for a single cloud).
  4. Use the new image IDs/names in your cloud deployment (e.g. Terraform, console, or CLI).

Publishing Images to Cloud Marketplaces

After Packer has produced new images, use these steps to publish them to the cloud marketplaces.

Replace version examples (e.g. 3.26.2) with the actual release version you are publishing.

Azure Marketplace (Partner Center)

  1. Go to https://partner.microsoft.com/.
  2. Click Partner Center (top-right) and log in.
  3. In the left navigation, open Marketplace offers.
  4. Select the Appcircle Server offer (e.g. acserverv0).
  5. Go to Plan overview → select the Plan BYOL plan.
  6. Open the Technical configuration tab.
  7. Under VM images, click Add VM image and fill in:
  8. Version number: <VERSION> (e.g. 3.26.2).
  9. Add a gallery image:
    • Image type: x64 Gen1 and/or x64 Gen2 (matching what we built).
    • Gallery image: Appcircle-Server.
    • Gallery image version: <VERSION> (same as above).
  10. Click Save at the bottom of the page.
  11. Click Review and publish.
  12. At the Publisher signoff step, click Go live.
  13. Wait for the publish process to complete (status in Partner Center).

AWS Marketplace

  1. Log in to the AWS Marketplace Management Portal.
  2. Open the Appcircle Server product:
    https://aws.amazon.com/marketplace/management/products/prod-csqadmmuihsnk/overview
  3. Go to the Versions page:
    https://aws.amazon.com/marketplace/management/products/prod-csqadmmuihsnk/overview/versions
  4. Click Add version and fill in:
  5. Version title: <VERSION> (e.g. 3.26.2).
  6. AMI ID: the AMI ID created by the Packer build for this release.
  7. Role ARN: arn:aws:iam::813745330516:role/AmiIngest.
  8. Save and follow the AWS Marketplace workflow to validate and publish the new version.

References