A lightweight application to renew your SSL certificates in an automated fashion
Table of Contents
Managing SSL certificates manually across multiple systems is time-consuming, error-prone, and can lead to service outages if certificates expire unexpectedly. This tool is designed to automate SSL certificate renewal across various environments, ensuring that your applications and services remain secure and compliant without the hassle of manual intervention.
By supporting multiple systems, it simplifies certificate management for developers, sysadmins, and DevOps teams alike.
- Prevent downtime due to expired certificates
- Maintain strong HTTPS security standards
- Save time with reliable automation
- Standardize renewal workflows across different platforms
- Centralized management certificates and logging
- No SPOF due to wildcard certificates (each instance get's a unique domain specific certificate)
- Easily scalable
Follow these steps to get the tool up and running:
-
System Requirements
- Python v3.13 or higher
- Docker Engine v28.1.1 or higher
- Git v2.49.0 or higher
- GNU Bash v5.2.0 or higher
-
System Access
- Access to target systems
- API tokens or credentials for authentication
⚠️ Important: Certicopter does not provide built-in interfaces for resolving or securing credentials. All sensitive information - such as passwords, usernames, domain names, API tokens, and similar - is expected to be supplied via environment variables. The mechanism responsible for storing and providing these environment variables must be maintained by the user.
As part of the guided setup, users receive a template tailored to their requirements. This template includes a checklist of the necessary environment variables but does not handle their the provisioning or secure storage.
- Network Requirements
- HTTPS/HTTP access to target systems
- DNS resolution for target domains
- Port access (varies by system and you configurations, typically 80, 443, 8443, 9440, 9443)
-
Clone the repository
git clone https://github.com/amanoxsolutions/certicopter.git
-
Execute the
setup.shfile
- Open Git Bash and navigate to the project folder
cd PathTo/certicopter ./setup.sh
⚠️ Important: If you encounter an error while trying to execute one of the shell scripts mentioned above, you may need to modify its execution permissions. As an example:chmod +x setup.shIf you encounter syntax errors while executing the script, it's likely due to using the wrong shell. Always open and run the script in the Git Bash shell to avoid such errors.
-
Enter all necessary information
- DNS hosting provider (only those that are offered from Certbot -> DNS Plugins)
- Notification email address
- Save certificates locally or not
- Systems used
- Instances per system
-
Create the necessary environment variables in your secrets manager depending on your internal architecture
- Use the
env_template.envfile created by thesetup.sh - The environment variables on your side must match those in the template for the script to correctly resolve the values
- Use the
📌 If you do not have a dedicated infrastructure or system for securely storing and managing your credentials (and providing them as environment variables), you can create a
.envfile. Then, add the'env_file'tag to thedocker-compose.ymlfile to use this method.
- Enable Hosting Provider Plugin
- Go to the
SSL_Certificate_App/requirements.txtand activate the plugin depending on what hosting provider you have chosen - To activate it, remove the
#in front of yourcertbot-dns-exampleprovider
- Go to the
- Guided Execution (recommended)
- Execute the
run.shfile in the project directory./run.sh
- Docker Standalone Execution
docker compose up --build
To ensure your SSL certificates are automatically renewed before they expire, you should set up a recurring task (we suggest performing this in a monthly fashion). Here are the recommended approaches as examples:
- Using a Cron Job
- Edit your crontab:
crontab -e - Add a monthly job:
0 0 1 * * /path/to/certicopter/run.sh --noninteractive
- Edit your crontab:
📌 The above command executes the shell script on a monthly basis at midnight without the need for manual interaction.
- Using Windows Task Scheduler
- Open Task Scheduler
- Create a new Task
- Set the trigger to Monthly
- Select all months
- Set day to 1
- Start time: 00:00
- Action: Start a program
- Program/script:
C:\Program Files\Git\bin\bash.exe - Add arguments:
-c "/c/User/path/to/certicopter/run.sh --noninteractive"
⚠️ Important:
- Ensure the scheduling interval is less than your certificate validity period (< 90 days)
- Monitor the logs for successful renewals
- Test the renewal process manually before setting up automation
The application uses a JSON-based configuration file (config.json) with the following example structure (generated automatically with the guided setup process):
{
"certicopter_global_settings": {
"hosting_provider": "example_provider",
"notification_email": "example.email@example.com",
"save_certificates": "y"
}
"providers": {
"nutanix|paloalto|vsphere|rubrik|hycu|vamax": {
"instances": [
{
"domain_env_var": "PROVIDER_INSTANCE_1_DOMAIN",
"username_env_var": "PROVIDER_INSTANCE_1_USERNAME",
"password_env_var": "PROVIDER_INSTANCE_1_PASSWORD"
},
{
"domain_env_var": "PROVIDER_INSTANCE_2_DOMAIN",
"username_env_var": "PROVIDER_INSTANCE_2_USERNAME",
"password_env_var": "PROVIDER_INSTANCE_2_PASSWORD"
}
]
}
}
}Documentation for this project can be found in the docs/ directory:
app_architecture- Explanation how the application in general and it's components workcoding_guidelines.md- Coding standards and best practicesenpoints.md- API documentation and endpointscommon_errors.md- List of most common errors that can happen during execution
Additional documentation is available in the code comments and docstrings. The main README provides only a high-level overview of the project.
- Initial release with basic functionality
- Support for multiple systems
- Automated certificate renewal
- Basic error handling and logging
- Basic testing coverage
- CI/CD pipeline
- Additional system integrations
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/NewFeature) - Commit your Changes (
git commit -m 'Added a new feature') - Push to the Branch (
git push origin feature/NewFeature) - Open a Pull Request
Axians Amanox AG - Website - opensource@amanox.ch
Project Link: https://github.com/amanoxsolutions/certicopter
This project is licensed under the Apache License 2.0. See the LICENSE file for details.