{"id":25150226,"url":"https://github.com/igladi/amicompatible","last_synced_at":"2026-03-02T06:31:23.582Z","repository":{"id":275458390,"uuid":"898560491","full_name":"IGLADI/AmICompatible","owner":"IGLADI","description":"AIC is a cross-platform software compatibility testing tool.","archived":false,"fork":false,"pushed_at":"2025-03-07T18:27:16.000Z","size":99,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-08T11:07:42.509Z","etag":null,"topics":["azure","cicd","devops","jenkins"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IGLADI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-04T16:02:17.000Z","updated_at":"2025-03-13T17:37:15.000Z","dependencies_parsed_at":"2025-02-02T17:35:46.451Z","dependency_job_id":"f274173d-4f98-40ab-b8c0-701abf709145","html_url":"https://github.com/IGLADI/AmICompatible","commit_stats":null,"previous_names":["igladi/amicompatible"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/IGLADI/AmICompatible","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IGLADI%2FAmICompatible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IGLADI%2FAmICompatible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IGLADI%2FAmICompatible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IGLADI%2FAmICompatible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IGLADI","download_url":"https://codeload.github.com/IGLADI/AmICompatible/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IGLADI%2FAmICompatible/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29994122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure","cicd","devops","jenkins"],"created_at":"2025-02-08T22:17:54.772Z","updated_at":"2026-03-02T06:31:23.506Z","avatar_url":"https://github.com/IGLADI.png","language":"Python","readme":"\u003c!-- Disclaimer: This README has been made w help of AI as well as a lot of documentation in the code --\u003e\n\n# AmICompatible\n\n## Overview\n\nAmICompatible (AIC) is a tool designed to help you test the compatibility of your software across different platforms. Whether you already have a [Jenkins](https://www.jenkins.io) pipeline in place or prefer to start with a simple [Jenkinsfile](https://www.jenkins.io/doc/pipeline/tour/hello-world/) that runs your script, AIC can help you quickly identify any compatibility issues with your software.\n\n## Use Cases\n\n-   **Script Compatibility Testing**: Quickly document which Linux distributions your script runs on by creating a Jenkinsfile that just executes the script.\n\n    -   Example: Deploy an Nginx website =\u003e Run with AIC =\u003e Discover UFW is missing on some distros =\u003e Fix or document it.\n\n-   **Software Retrocompatibility**: Test how well your software runs across different Windows versions.\n\n-   **[Upcoming] Emulation Layer Testing**: Check how well your software performs with emulation layers like [Wine](https://www.winehq.org) or Proton for [Linux users.](https://www.protondb.com/explore)\n\n-   **Quick Pipeline Execution**: Test a Jenkins pipeline without manually setting up a local Jenkins server.\n\n## Prerequisites\n\n-   [Python 3.x](https://www.python.org/downloads/)\n-   [Terraform](https://www.terraform.io/downloads.html)\n-   [Azure Subscription](https://azure.microsoft.com/en-us/pricing/purchase-options/azure-account?icid=azurefreeaccount)\n-   [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)\n-   [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)\n-   **Note**: ⚠️ Because AIC relies on Ansible, a Linux environment is required. If on Windows, please use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) or a Linux VM.\n\n## Quick Start\n\n1. **Clone Repository**\n\n    ```bash\n    git clone https://github.com/IGLADI/AmICompatible \u0026\u0026 cd AmICompatible\n    ```\n\n2. **Install dependencies**\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n3. **Create Azure Service Principal**\n\n    ```bash\n    az login\n\n    az ad sp create-for-rbac --name \"AIC\" --role contributor --scopes /subscriptions/\u003csubscription_id\u003e\n    ```\n\n    \u003e **Note**: Alternatively, you can create the Service Principal through the [Azure Portal](https://portal.azure.com) if you prefer not to use the CLI.\n\n4. **Edit the configuration file as needed**\n\n    Copy `aic.yml.example` to `aic.yml`:\n\n    ```bash\n    cp aic.yml.example aic.yml\n    ```\n\n    Update `aic.yml`:\n\n    ```bash\n    nano aic.yml\n    ```\n\n5. **Run AIC**\n\n    This would typically be done using GitHub Actions or similar (which would also handle the secrets in `aic.yml`).\n\n    ```bash\n    python main.py\n    ```\n\n## Limitations\n\nAIC will install dependencies which might not come with the system. If your code uses these dependencies, it might work on AIC but not on a clean system. For example, Java will be installed by AIC but not present on a clean system.\n\nAIC handles interruptions as much as possible; however, Terraform can be very sensitive to them, so interruptions are still seriously discouraged and you should always check for any cloud resources left when doing so to avoid any unnecessary costs.\n\n\u003e **Note**: If using GitHub Actions, please note that the system forcibly terminates processes after a timeout when canceled, which may not allow enough time for Azure resources to be properly cleaned up. Cancellation is generally unnecessary in CI/CD environments since multiple runs can execute concurrently (each using separate environments with their own `.tfstate` files). Our current implementation only handles the `SIGINT` signal, if your CI/CD system uses a different signal, please inform us so we can add support for it.\n\n## How to Add Providers\n\nTo add support for additional cloud providers or on-premises infrastructure, follow these steps:\n\n### Method 1: Create a New Terraform Directory\n\n1. **Create a new Terraform directory for the provider**\n\n    ```bash\n    mkdir terraform/aws\n    ```\n\n2. **Add Terraform configuration files**\n\n    Add the necessary Terraform configuration files in the newly created directory to define the infrastructure for the provider.\n\n3. **Modify the `main.py` script**\n\n    ```bash\n    nano main.py\n    ```\n\n    Example:\n\n    ```python\n    match cfg[\"platform\"]:\n        case \"azure\":\n            terraform_dir = \"./terraform/azure\"\n        case \"aws\":\n            terraform_dir = \"./terraform/aws\"\n        case _:\n            print(f\"Error: Unsupported platform '{cfg['platform']}' specified.\")\n            sys.exit(1)\n    ```\n\n    **Note**: You could also just change this code to use the provider name as directory name. Don't forget to try catch the `FileNotFoundError` exception.\n\n    You may also need to update `config.py` to include any provider-specific variables.\n\n    ```bash\n    nano ./modules/config.py\n    ```\n\n4. **Update the configuration file**\n\n    Ensure that the configuration file (`aic.yml`) includes the new provider and any required variables.\n\n### Method 2: Edit Existing Terraform File with Environment Variables\n\n1. **Move the existing Terraform files**\n\n    ```bash\n    mv terraform/azure/* terraform/\n    ```\n\n2. **Edit the Terraform files**\n\n    Update the Terraform files to use environment variables for provider-specific configurations.\n\n3. **Modify the `main.py` script**\n\n    Update the `config.py` script to set the appropriate environment variables based on the provider specified in the configuration.\n\n    ```bash\n    nano ./modules/config.py\n    ```\n\n    Update the `main.py` script to work with one terraform directory.\n\n    ```python\n    terraform_dir = \"./terraform\"\n    ```\n\n4. **Update the configuration file**\n\n    Ensure that the configuration file (`aic.yml`) includes the new provider and any required variables.\n\n## How to Add Supported OS\n\nTo add support for additional operating systems, follow these steps:\n\n1. **Update Terraform Main Configuration**\n\n    Add the new OS to the `source_image_reference` lookup in the `main.tf` file for both Windows or Linux configurations.\n\n    ```terraform\n    source_image_reference {\n      publisher = lookup({\n        LinuxUbuntuServer_24_04-LTS = \"Canonical\",\n        LinuxRhel9                  = \"RedHat\",\n        LinuxDebian12               = \"Debian\",\n        \u003cnew_os\u003e                    = \"\u003cnew_publisher\u003e\"\n      }, var.os)\n      offer = lookup({\n        LinuxUbuntuServer_24_04-LTS = \"ubuntu-24_04-lts\",\n        LinuxRhel9                  = \"RHEL\",\n        LinuxDebian12               = \"debian-12\",\n        \u003cnew_os\u003e                    = \"\u003cnew_offer\u003e\"\n      }, var.os)\n      sku = lookup({\n        LinuxUbuntuServer_24_04-LTS = \"server\",\n        LinuxRhel9                  = \"90-gen2\",\n        LinuxDebian12               = \"12-gen2\",\n        \u003cnew_os\u003e                    = \"\u003cnew_sku\u003e\"\n      }, var.os)\n      version = \"latest\"\n    }\n    ```\n\n2. **Update Configuration File**\n\n    Add the new OS to the `aic.yml` and `aic.yml.example` files.\n\n    ```yaml\n    os:\n        # - UbuntuServer_24_04-LTS\n        # - Debian12\n        # - RHEL9\n        # - \u003cnew_os\u003e\n    ```\n\n3. **Add OS-Specific Code**\n\n    If the new OS requires any specific setup or dependencies, update the corresponding code, this will likely be in the `ansible/linux/dependency.yml`\n\n## Contributing\n\nTo contribute your changes (like adding support for a new provider), follow these steps:\n\nFork the repository and clone it to your local machine.\n\nCreate a new feature branch.\n\n```bash\ngit checkout -b feature/add-aws-support\n```\n\nCode your changes and commit them.\n\n```bash\ngit add .\ngit commit -m \"Add AWS support\"\n```\n\nPush to your fork.\n\n```bash\ngit push origin feature/add-aws-support\n```\n\n\u003e ℹ️ Ensure you document your changes and update the README if necessary.\n\nOpen a PR on the main repository to merge your changes.\n\nThank you for contributing to the open-source community!\n\n## Troubleshooting\n\n### VM Image Issues\n\nIf you encounter any issue while terraform deploys a specific VM image:\n\n-   Check if your subscription tier is eligible for that image (a lot of images are not available for free plans).\n-   Accept TOS when needed:\n\n    ```bash\n    az vm image terms accept --publisher resf --offer rockylinux-x86_64 --plan 9-base\n    az vm image terms accept --publisher ntegralinc1586961136942 --offer ntg_fedora_41 --plan ntg_fedora_41\n    ```\n\n\u003e ℹ️ We try to keep all TOS commands needed here, if you encounter one not listed here please contribute or open an issue.\n\n### Terraform Apply Issues\n\nIf you encounter any issues with terraform, this is most likely due to a mismatch between the tfstate file and the actual resources in the cloud. To fix this, you can delete the tfstate file **and** delete any resources that were created by the script manually.\n\n```bash\nrm ./terraform/azure/linux/*.tfstate* \u003e /dev/null 2\u003e\u00261\nrm ./terraform/azure/windows/*.tfstate* \u003e /dev/null 2\u003e\u00261\n```\n\n\u003e ℹ️ You will need to wait for the resources to be deleted before running the script again.\n\n### Azure Limitations\n\nIf you encounter an Azure limitation, for example `PublicIPCountLimitReached` try decreasing `max_threads` in `aic.yml` or increase your subscription limits if you are on a paid plan.\n\n### Windows SSH Extension Issues\n\nThe extension has a timeout of ~3 minutes to setup ssh, if you encounter any issues with the extension, try increasing `vm_size` in `aic.yml`.\n\n### OSError: Too many open files\n\nIf you encounter the error `OSError: [Errno 24] Too many open files`, try decreasing `max_threads` in `aic.yml`.\n\n### Jenkins pipeline failed. This is not an AIC error.\n\nCheck the `jenkins.log` file inside the `aic_logs` folder. Navigate to the folder of the run you want, then the OS folder you want, and open `jenkins.log`. Typically, the information you are interested in will be at the end of the file.\n\n### Check Logs\n\nIf you encounter any issues, checking the logs can provide more insight into what went wrong. Logs are typically stored in the `~/.aic_logs` directory, this can be changed in the `aic.yml` file. The logs contain ansi colors, you can use `cat` or other to interpret them, if you want to use vscode to read the logs we recommend the `Ansi Colors` extension.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figladi%2Famicompatible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figladi%2Famicompatible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figladi%2Famicompatible/lists"}