6.0 KiB
Vigil
Vigil is a simple Python based program for set and forget servers that checks for apt updates at fixed intervals and emails you when updates are available, allowing you to upgrade the server using replies.
Vigil is designed for stability and security, avoiding keeping credentials in the memory of the server for extended periods and helping keep your server up to date.
Table of Contents
Local Installation
These instructions will help you run Vigil on your own server using the git repository, if you want to use this software in production, refer to Installation instead.
Prerequisites
- Python 3.8+
- Git
- SMTP server
- IMAP server
Installation and Running
First clone the repository into a new directory:
git clone https://git.uthmn.com/ufatih/vigil.git
Now change into the directory:
cd vigil
Then create a .env file in the root directory with the following contents:
SMTP_SERVER=
SMTP_PORT=
SMTP_USERNAME=
SMTP_PASSWORD=
IMAP_SERVER=
IMAP_PORT=
IMAP_USERNAME=
IMAP_PASSWORD=
Fill in the values for the environment variables with the correct values for your SMTP and IMAP servers.
Now create a users.json file in the root directory with a list of email addresses to receive and manage server updates, i.e:
[
"email1@example.com",
"email2@example.com"
]
Now we can initialise a new virtual environment and install the required packages:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Finally, we can run the program:
sudo .venv/bin/python3 main.py serve
This will check for updates every hour and send an email to the provided email addresses.
Installation
The easiest way to install Vigil is by using the interactive install script.
This script automatically checks for required dependencies, offers to install any that are missing, and can optionally configure Vigil to start automatically on boot via systemd.
Run the following command:
curl -sSL -o install.sh https://git.uthmn.com/ufatih/vigil/raw/main/install.sh
sudo bash install.sh
rm install.sh
You can also review the script before executing it:
curl -sSL https://git.uthmn.com/ufatih/vigil/raw/main/install.sh -o install.sh
less install.sh
sudo bash install.sh
rm install.sh
You can also uninstall Vigil using the following command:
curl -sSL -o uninstall.sh https://git.uthmn.com/ufatih/vigil/raw/main/uninstall.sh
sudo bash uninstall.sh
rm uninstall.sh
You can also review the script before executing it:
curl -sSL https://git.uthmn.com/ufatih/vigil/raw/main/uninstall.sh -o uninstall.sh
less uninstall.sh
sudo bash uninstall.sh
rm uninstall.sh
Usage
Once installed, Vigil can be run in two modes:
Scheduled mode (recommended): Runs continuously and checks for updates at a fixed interval (hourly or daily).
Immediate mode: Performs a one-off update check and exits.
Running Vigil
If installed via the install script or pipx, simply use:
vigil serve
If running from the repository directly:
sudo .venv/bin/python3 main.py serve
Vigil provides two main commands:
1. Scheduled Mode (serve)
Runs Vigil continuously, checking for updates based on the provided schedule and emailing the results.
vigil serve [OPTIONS]
Options (serve)
| Option | Description | Default |
|---|---|---|
| --receiver-email | Comma-separated list of email addresses to send updates to | Reads from users.json if not provided |
| --check-hourly | Enables hourly update checks | False |
| --check-daily | Enables daily update checks at a specific UTC hour (e.g. --check-daily 18) | 18 |
Examples
Check for updates every hour:
sudo vigil serve --check-hourly --receiver-email "admin@example.com, security@example.com"
Check for updates daily at 18:00 UTC:
sudo vigil serve --check-daily 18
2. Immediate Mode (now)
Performs a single update check, emails the results, and exits.
vigil now [OPTIONS]
Options (now)
| Option | Description | Default |
|---|---|---|
| --receiver-email | Comma-separated list of email addresses to send updates to | Reads from users.json |
Example
sudo vigil now --receiver-email "admin@example.com"
Email Configuration
If --receiver-email is not provided, Vigil looks for a file named users.json in the same directory as the executable, containing a list of recipient email addresses:
[
"email1@example.com",
"email2@example.com"
]
Systemd Integration
If you installed Vigil using the install script, it can optionally create a systemd service for automatic startup at boot. You can manually control the service as follows:
sudo systemctl start vigil # Start vigil
sudo systemctl stop vigil # Stop vigil
sudo systemctl enable vigil # Enable vigil to start at boot
sudo systemctl status vigil # Check the status of vigil
This ensures Vigil runs continuously and automatically checks for updates at your configured interval.
Notes
Vigil requires root privileges to check and list available APT updates.
When running inside Docker, environment variables and configuration files (.env, users.json) should be mounted or baked into the image.
Logs and errors are printed to standard output (and journalctl if running as a service).