{"id":20238453,"url":"https://github.com/smallstep/butane-smallstep-acme-ra","last_synced_at":"2026-02-23T13:16:57.705Z","repository":{"id":80686004,"uuid":"526666889","full_name":"smallstep/butane-smallstep-acme-ra","owner":"smallstep","description":"Butane smallstep ACME RA for Fedora CoreOS","archived":false,"fork":false,"pushed_at":"2022-09-13T18:11:34.000Z","size":17,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-02-25T09:58:42.546Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jinja","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/smallstep.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}},"created_at":"2022-08-19T15:52:35.000Z","updated_at":"2025-01-06T21:19:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"dfa82282-bbdb-4ea1-bfe8-bf412d020b76","html_url":"https://github.com/smallstep/butane-smallstep-acme-ra","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fbutane-smallstep-acme-ra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fbutane-smallstep-acme-ra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fbutane-smallstep-acme-ra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallstep%2Fbutane-smallstep-acme-ra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smallstep","download_url":"https://codeload.github.com/smallstep/butane-smallstep-acme-ra/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241685559,"owners_count":20003102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-14T08:34:14.041Z","updated_at":"2025-10-25T18:42:46.786Z","avatar_url":"https://github.com/smallstep.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Butane smallstep ACME RA\n\nThis is a repo for launching an step-ca setup as an ACME RA with a Jinja2 template. You can render it easily with [Bupy](https://github.com/quickvm/bupy). Just customize the `butanevars.yaml` file and run Bupy to process it.\n\n```\nbupy template smallstep-acme-ra.bu.j2 butanevars.yaml --show\n```\n\nYou can use this with a free smallstep Certificates Manager account (signup [here](https://smallstep.com/signup?product=cm)!) or with https://github.com/smallstep/certificates.\n\n## Setup\n\n## smallstep Certificate Manager RA\n\nThe smallstep [Certificate Manager](https://smallstep.com/signup?product=cm) product offers an automated setup to configure an ACME RA. You can create a new CA to be used with an ACME RA which will walk you through the setup. Just goto `https://smallstep/app/\u003csmallstep team name\u003e/cm/authorities/add?step=0` to start this process. Once you have your CA setup to be used with an ACME RA you will see a RA Token and Password. Copy those as you will need them when you configure the butanevars.yaml file to setup your RA.\n\n### Customize butanevars.yaml\n\nReplace the example SSH key with your SSH key on the `core` user and replace `yourusername` with your POSIX username and replace the example SSH key with your SSH key:\n\n```\npasswd:\n  users:\n  - name: core\n    ssh_authorized_keys:\n      - ssh-ed25519 AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29tAAAAIaaaaaaaaaaaaaaaaaaaaaaaaaaa you@example.com\n  - name: yourusername\n    ssh_authorized_keys:\n      - ssh-ed25519 AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29tAAAAIaaaaaaaaaaaaaaaaaaaaaaaaaaa you@example.com\n    groups:\n      - wheel\n      - sudo\n```\n\nSet a `hostname` and `domainname` for your RA. By default Fedora CoreOS will be configured to auto update at 11AM CT on Monday every week. Fedora CoreOS provides a rolling release and is ver stable on upgrades. In most cases, if your deployment can handle a few minutes of downtime on your RA, you can leave auto updates turned on. You can disable auto updates if you like by setting `auto: false`. If you turn off automatic updates please see the [FCOS documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/auto-updates/) on how to manage your updates manually.\n\n```\nsystem:\n  hostname: smallstep-acme-ra\n  domainname: example.com\n  updates:\n    auto: true\n    time_zone: America/Chicago\n    rollout_wariness: 1\n    days: '[ \"Mon\" ]'\n    start_time: \"11:00\"\n    length_minutes: \"60\"\n```\n\nThe last thing you will need to add is the smallstep CA token and provisioner password to `smallstep_ca_token` and `smallstep_provisioner_password` respectively.\n\n```\nstepca:\n  smallstep_ca_token: \u003cstep-acme-ra-token-from-smallstep.com\u003e\n  smallstep_provisioner_password: \u003cstep-provisioner-password-from-smallstep.com\u003e\n```\n\n**Render the smallstep ACME RA template**\n\nYou can view the rendered template by using [Bupy](https://github.com/quickvm/bupy).\n\n```\n$ bupy template smallstep-acme-ra.bu.j2 butanevars.yaml --show\n    1 variant: fcos\n    2 version: 1.4.0\n    3 passwd:\n    4   users:\n    5   - name: core\n    6     ssh_authorized_keys:\n    7       - sk-ssh-ed25519@openssh.com AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29tAAAAIaaaaaaaaaaaaaaaaaaaaaaaaaaa example@example.com\n    8   - name: example\n    9     groups:\n   10       - wheel\n   11       - sudo\n   12     ssh_authorized_keys:\n   13       - sk-ssh-ed25519@openssh.com AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29tAAAAIaaaaaaaaaaaaaaaaaaaaaaaaaaa example@example.com\n   14   - name: step\n   15     system: true\n   16\n   17 storage:\n   18   directories:\n   19   - path: /etc/step\n   20     mode: 0700\n   21   - path: /etc/step-ca\n   22     mode: 0700\n   ...snip...\n```\n\nand save it to a file:\n\n```\nbupy template smallstep-acme-ra.bu.j2 butanevars.yaml --write smallstep-acme-ra.ign\n```\n\n### Launch smallstep ACME RA\n\nYou can now take the Ignition file you have just created from the Butane template (`smallstep-acme-ra.ign` in this example) and use that to launch your smallstep ACME RA. Fedora CoreOS supports a vast number of cloud providers and even bare metal deployments (even [Raspberry Pi 4](https://docs.fedoraproject.org/en-US/fedora-coreos/provisioning-raspberry-pi4/)!). See the [FCOS documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/) for full details. Here are a few examples:\n\n**Locally on Linux**\n\n```\nbupy vm smallstep-acme-ra.bu.j2 --template butanevars.yaml -p 443\n```\n\n**AWS**\n\n```\nNAME='acme-ra.example.com'\nREGION='us-east-2'  # the target region\nAMI=$(curl -sSL https://builds.coreos.fedoraproject.org/streams/stable.json | jq --arg region ${REGION} -r '.architectures.x86_64.images.aws.regions[$region].image')\nSSHKEY='my-key'     # the name of your SSH key: `aws ec2 describe-key-pairs`\nDISK='20'           # the size of the hard disk\nTYPE='m5.large'     # the instance type\nSUBNET='subnet-xxx' # the subnet: `aws ec2 describe-subnets`\nSECURITY_GROUPS='sg-xx' # the security group `aws ec2 describe-security-groups`\nUSERDATA='smallstep-acme-ra.ign' # path to your Ignition config\naws ec2 run-instances                     \\\n    --region $REGION                      \\\n    --image-id $AMI                       \\\n    --instance-type $TYPE                 \\\n    --key-name $SSHKEY                    \\\n    --subnet-id $SUBNET                   \\\n    --security-group-ids $SECURITY_GROUPS \\\n    --user-data \"file://${USERDATA}\"      \\\n    --tag-specifications \"ResourceType=instance,Tags=[{Key=Name,Value=${NAME}}]\" \\\n    --block-device-mappings \"VirtualName=/dev/xvda,DeviceName=/dev/xvda,Ebs={VolumeSize=${DISK}}\"\n```\n\n**Google Compute**\n\n```\nSTREAM='stable'\nVM_NAME='acme-ra.example.com'\nCONFIG='smallstep-acme-ra.ign'\ngcloud compute instances create --metadata-from-file \"user-data=${CONFIG}\" --image-project \"fedora-coreos-cloud\" --image-family \"fedora-coreos-${STREAM}\" \"${VM_NAME}\"\n```\n\n## Open Source\n\nYou can use this automation without a smallstep [Certificate Manager](https://smallstep.com/signup?product=cm) account and use it with https://github.com/smallstep/certificates. The `butanevars.yaml` file has some commented out variables that you can use to configure the Butane template to not use a token from smallstep Certificate Manager. Just comment out `smallstep_ca_token` and `smallstep_provisioner_password` and uncomment and configure the other variables. See\n\n```\nstepca:\n  # smallstep_ca_token: \u003cstep-acme-ra-token-from-smallstep.com\u003e\n  # smallstep_provisioner_password: mysupersecretpassword\n  # Manually configure a step-ca ACME RA\n  smallstep_ca_fingerprint: my_smallstep_ca_fingerprint\n  smallstep_ca_url: https://myacme.myteam.ca.mystepca.biz\n  smallstep_provisioner: acme-ra\n  smallstep_ra_address: :443\n  smallstep_ra_dns_names: acme.example.com\n```\n\n## Getting a certificate with Certbot\n\n```\nstep ca root --ca-url mycool-ca.example.com --fingerprint my-ca-fingerprint \u003e /tmp/mycool-ca.example.com-root.pem\nsudo REQUESTS_CA_BUNDLE=/tmp/mycool-ca.example.com-root.pem ACME_RA_PROVISIONER=my-acme-provisoner ACME_RA_URL=https://mycool-ca.example.com:443 certbot certonly --standalone --preferred-challenges http-01 --work-dir .certbot --logs-dir .certbot --config-dir .certbot --agree-tos --server ${ACME_RA_URL}/acme/{ACME_RA_PROVISIONER}/directory --email you@example.com --domains my-domain.example.com\n```\n\n## Getting a certificate with step CLI\n\n```\nstep ca root --ca-url mycool-ca.example.com --fingerprint my-ca-fingerprint \u003e /tmp/mycool-ca.example.com-root.pem\nsudo REQUESTS_CA_BUNDLE=/tmp/mycool-ca.example.com-root.pem ACME_RA_PROVISIONER=my-acme-provisoner ACME_RA_URL=https://mycool-ca.example.com:443 step ca certificate --standalone --acme=${ACME_RA_URL}/acme/{ACME_RA_PROVISIONER}/directory my-domain.example.com example.localhost.crt example.localhost.key --root=${REQUESTS_CA_BUNDLE}\n```\n\n## Security\n\nIt is important that you do not run your smallstep ACME RA on the public Internet. Any ACME client that can access your RA and go through the ACME workflow using the HTTP challenge will be issued a certificate from your CA. When you launch your ACME RA, please ensure that you use best practices with security groups or firewalls to prevent unwanted access. You can also configure configure your CA with some additional controls for certificate issuance. Plese see the smallstep [documentation](https://smallstep.com/docs/certificate-manager/acme/how-to-use-acme/#certificate-issuance-policies) for more information.\n\n## License\n\nMIT License\n\nCopyright (c) 2022 Smallstep Labs, Inc\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallstep%2Fbutane-smallstep-acme-ra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmallstep%2Fbutane-smallstep-acme-ra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallstep%2Fbutane-smallstep-acme-ra/lists"}