Overview

CircleCI Server requires specific components to be pre-installed on your AMI for proper functionality. Before deploying CircleCI Server, your AMI must include essential components: a dedicated circleci user account, Git, Docker, curl, sha256sum, tar, and the ability to execute a binary from /tmp/. These requirements ensure that CircleCI Server can execute builds. 

Required AMI Components

Your CircleCI Server AMI must include the following mandatory components:

• CircleCI User Account - A dedicated circleci user must be created on the system with appropriate permissions to run CircleCI processes and access necessary system resources during build operations.
• Git Installation - Git version control system must be installed and accessible from the command line, enabling CircleCI Server to clone repositories, manage source code, and perform version control operations during the build process.
• Docker Installation - Docker must be properly installed, configured, and running on the AMI to support containerized build environments and job execution that CircleCI Server relies on for running user workloads.
• Curl Installation - The curl command-line tool must be installed and accessible to enable CircleCI Server to download dependencies, communicate with APIs, and transfer data during build processes and job execution.
• sha256sum Utility - The sha256sum utility must be available for file integrity verification and checksum validation. CircleCI Server uses this tool to verify downloaded artifacts and ensure data integrity during build operations.
• Tar Archive Tool - The tar utility must be installed to handle archive extraction and compression operations. CircleCI Server requires tar for managing build artifacts, dependencies, and compressed files during job execution.
• Executable Permissions for /tmp/ - The system must allow execution of binaries from the /tmp/ directory. 

Common Issues When Components Are Missing

Missing required components can cause various job execution problems. Here are the most common symptoms you may encounter:

• Jobs Stuck in Queuing State - Missing circleci user account, sha256sum utility, executable permissions for /tmp/, or curl installation will cause jobs to remain in the queue indefinitely and never start. These components are required for CircleCI Server to properly initialize and allocate resources for job execution.
• Git Checkout Issues - Missing Git installation may cause the built-in - checkout step to fall back to CircleCI's internal Git implementation, which might not be as useful or fully featured as a proper Git installation. For optimal functionality, ensure Git is properly installed on the AMI.
• Archive Extraction Failures - Missing tar utility causes specific build steps to fail when attempting to extract compressed dependencies, cache files, or build artifacts. You'll see "tar: command not found" errors during cache restoration or artifact processing steps.

Additional Notes

Verify that the Docker service is configured to start automatically on boot and that the circleci user has the necessary permissions to interact with Docker if your builds require container operations. Some CircleCI Server configurations may require additional Docker permissions or group memberships for the circleci user account.

Additional Resources

• CircleCI Server Installation Guide - Complete installation documentation
• Docker Installation Requirements - Detailed Docker setup requirements
• Adding CloudWatch to your AMI - Detailed CloudWatch requirements