svs-core 0.14.3

Core library for SVS (https://svs.kristn.co.uk/)

Self-Hosted Virtual Stack

SVS is an open-source python library for managing self-hosted services on a linux server.

CI:

Docs

For full docs, visit svs.kristn.co.uk

This readme contains a quick summary and development setup info.

Goals

The goal of this project is to simplify deploying and managing self-hosted applications on a linux server. Inspired by Portainer but aimed at begginer users. Under the hood, all applications are containerized using Docker. For ease of use, the library provides pre-configured service templates for popular self-hosted applications such as:

• MySQL
• PostgreSQL
• Django
• NGINX
• ...

Technology overview

Every service will run a Docker container and all of users' services will be on the same Docker network, allowing them to communicate with each other easily without

1. exposing them to other users on the same server
2. having to use compose stacks and custom networks to allow cross-service communication.

Features

Currently, the library is in early development and has the following features:

• User management
• Docker network management
• Service management
• Service templates
• CI/CD integration
• DB/System sync issues + recovery
• Remote SSH access

Running locally

Given this repository accesses system files, creates docker containers and manages services and is designed strictly for linux servers, it is recommended to run in a virtual environment.

The easiest way to achieve a reproducible environment is to use the included devcontainer configuration. Devcontainers allow you to run a containerized development environment with all dependencies installed. See the devcontainer documentation.

The local devcontainer config creates the following compose stack:

1. A python devcontainer for the development environment.
2. A postgres database container for storing service data.
3. A caddy container to act as a HTTP proxy (needed only if testing domains locally)

This guide assumes you have chosen to use the devcontainer setup.

Starting the devcontainer

To start the devcontainer, open the repository in Visual Studio Code and select "Reopen in Container" from the command palette. This will build the container and start it.

After attaching to the devcontainer, the dependencies will be automatically installed. After that's done, you can launch a new terminal which will have the virtual environment activated automatically.

You also need to run the install-dev.sh script to configure your system for development. This script will create the required directories and configure permissions. It is a subset of the production install script.

After running the install script, switch to the svs-admins group by running

newgrp svs-admins

Linting + Formatting

The devcontainer includes pre-configured linting and formatting tools for Visual Studio Code and all files should be formatted on save. If you use a different editor, you can run the pre-commit hooks manually by running pre-commit run --all-files in the terminal to apply the formatting and linting rules.

Running the tests

To run the tests, you can use the pytest command in the terminal. This will run all tests in the tests directory. You can also run individual test files or functions by specifying their paths.

Tests are split into unit, integration and cli tests. They can be run separately by using the -m flag with pytest:

pytest -m unit
pytest -m integration
pytest -m cli

Running the docs

Python docstrings are used throughout the codebase to generate documentation. To generate the documentation, you can use the zensical command in the terminal. This will build the documentation and serve it locally. To run the documentation server, you can use the following command:

zensical serve