# Vigil

![Gitea Last Commit](https://img.shields.io/gitea/last-commit/uthmn/vigil?gitea_url=https%3A%2F%2Fgit.uthmn.com&link=https%3A%2F%2Fgit.uthmn.com%2Fufatih%2Fvigil%2Fcommits%2Fbranch%2Fmain)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)

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

- [Getting Started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation and Running](#installation-and-running)
- [Installation](#installation)
  - [Using the install script (recommended)](#using-the-install-script-recommended)
  - [Using pipx](#using-pipx)
  - [Using Docker](#using-docker)
- [Usage](#usage)
  - [Running Vigil](#running-vigil)
    - [1. Scheduled Mode (serve)](#1-scheduled-mode-serve)
    - [2. Immediate Mode (now)](#2-immediate-mode-now)
  - [Email Configuration](#email-configuration)
  - [Systemd Integration](#systemd-integration)
  - [Notes](#notes)

## Getting Started

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](#installation) instead.

### Prerequisites

- Python 3.8+
- Git
- SMTP server
- IMAP server

### Installation and Running

First clone the repository into a new directory:

```bash
git clone https://git.uthmn.com/ufatih/vigil.git
```

Now change into the directory:

```bash
cd vigil
```

Then create a `.env` file in the root directory with the following contents:

```bash
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:

```json
[
    "email1@example.com",
    "email2@example.com"
]
```

Now we can initialise a new virtual environment and install the required packages:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Finally, we can run the program:

```bash
sudo .venv/bin/python3 main.py serve
```

This will check for updates every hour and send an email to the provided email addresses.

## Installation

### Using the install script (recommended)

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:

```bash
curl -sSL https://git.uthmn.com/ufatih/vigil/raw/main/install.sh | sudo bash
```

 You can also review the script before executing it:

```bash
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 now run Vigil using the following command:

```bash
vigil
```

### Using pipx

If you prefer to use pipx, you can install Vigil using the following command:

```bash
pipx install vigil
```

You can now run Vigil using the following command:

```bash
vigil
```

### Using docker

> [!WARN]  
> The docker run command will not work yet and needs to be updated when released.

If you prefer to use Docker, you can download the latest Docker image from the [Docker Hub](https://hub.docker.com/r/uthmn/vigil)

```bash
docker pull uthmn/vigil
```

You can now run Vigil using the following command:

```bash
docker run -it --rm uthmn/vigil
```

## 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:

```bash
vigil serve
```

If running from the repository directly:

```bash
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.

```bash
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 <hour> | Enables daily update checks at a specific UTC hour (e.g. --check-daily 18) | 18

#### Examples

Check for updates every hour:

```bash
sudo vigil serve --check-hourly --receiver-email "admin@example.com, security@example.com"
```

Check for updates daily at 18:00 UTC:

```bash
sudo vigil serve --check-daily 18
```

### 2. Immediate Mode (now)

Performs a single update check, emails the results, and exits.

```bash
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

```bash
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:

```json
[
    "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:

```bash
sudo systemctl start vigil
sudo systemctl stop vigil
sudo systemctl enable vigil
sudo systemctl status 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).