{"id":16162916,"url":"https://github.com/fabriziosalmi/lws","last_synced_at":"2025-03-18T22:31:15.641Z","repository":{"id":254634345,"uuid":"847110660","full_name":"fabriziosalmi/lws","owner":"fabriziosalmi","description":"linux (containers) web services","archived":false,"fork":false,"pushed_at":"2024-12-06T19:14:46.000Z","size":720,"stargazers_count":59,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-17T00:24:21.435Z","etag":null,"topics":["cli","command-line","command-line-tool","docker","fun","lxc","lxc-containers","lxc-lxd","lxc-templates","proxmox","proxmox-cluster","proxmox-ve","scalability"],"latest_commit_sha":null,"homepage":"","language":"Python","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/fabriziosalmi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["fabriziosalmi"]}},"created_at":"2024-08-24T22:01:54.000Z","updated_at":"2025-03-14T00:27:03.000Z","dependencies_parsed_at":"2024-10-27T19:17:28.928Z","dependency_job_id":"d9cfc355-ad8f-431e-9ff8-210e6a38f185","html_url":"https://github.com/fabriziosalmi/lws","commit_stats":null,"previous_names":["fabriziosalmi/lws"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Flws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Flws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Flws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Flws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabriziosalmi","download_url":"https://codeload.github.com/fabriziosalmi/lws/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244318590,"owners_count":20433936,"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":["cli","command-line","command-line-tool","docker","fun","lxc","lxc-containers","lxc-lxd","lxc-templates","proxmox","proxmox-cluster","proxmox-ve","scalability"],"created_at":"2024-10-10T02:33:53.133Z","updated_at":"2025-03-18T22:31:15.635Z","avatar_url":"https://github.com/fabriziosalmi.png","language":"Python","funding_links":["https://github.com/sponsors/fabriziosalmi"],"categories":[],"sub_categories":[],"readme":"# lws\n\n**lws** is a Command-Line Interface (CLI) tool designed to streamline the management of Proxmox Virtual Environments (VE), LXC containers, and Docker services through a unified, efficient interface.\n\n\u003e [!WARNING]\n\u003e Unstable, untested release still under development :)\n\n[![asciicast](https://asciinema.org/a/8rE7H67VjQ15HQ9KtsJVMRR4O.svg)](https://asciinema.org/a/8rE7H67VjQ15HQ9KtsJVMRR4O)\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Features](#features)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Configuration](#configuration)\n- [Usage](#usage)\n  - [Proxmox Management](#proxmox-management)\n  - [LXC Container Management](#lxc-container-management)\n  - [Docker Management](#docker-management)\n  - [Client Configuration Management](#client-configuration-management)\n  - [Managing Instance Profiles](#managing-instance-profiles)\n  - [Managing Security Settings](#managing-security-settings)\n  - [Managing Scaling Thresholds and Triggers](#managing-scaling-thresholds-and-triggers)\n- [Security Considerations](#security-considerations)\n- [Best Practices](#best-practices)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n## Introduction\n\n**lws** was created to simplify and unify the management of Proxmox VE, LXC containers, and Docker services using a single command-line tool. Although powerful, **lws** is still in its early stages and was developed primarily for learning and exploration. It should be used with caution, especially in production environments.\n\n## Features\n\n### General\n- **Comprehensive Logging**: Supports detailed logging in both standard and JSON formats.\n- **Flexible Configuration**: YAML-based configuration for easy setup and management.\n- **Secure Operations**: Uses SSH for secure communications, with sensitive information masked in logs.\n\n### Proxmox Management\n- **Cluster Management**: Control and monitor Proxmox clusters, including service lifecycle operations.\n- **Resource Monitoring**: Monitor CPU, memory, disk, and network usage across Proxmox hosts.\n- **Host Operations**: Execute essential operations like rebooting and updating hosts.\n\n### LXC Container Management\n- **Lifecycle Management**: Start, stop, reboot, and terminate LXC containers with ease.\n- **Resource ng**: Dynamically adjust container resources (CPU, memory, storage).\n- **Snapshot Management**: Create, delete, and manage snapshots for containers.\n- **Security Group Management**: Implement and manage security groups and rules.\n\n### Docker Management\n- **Easy Setup**: Simplified installation and setup of Docker and Docker Compose on LXC containers.\n- **Application Deployment**: Deploy, update, and manage Docker Compose applications.\n- **Container Operations**: Manage Docker containers, including running, stopping, and fetching logs.\n- **Auto-start Configuration**: Configure Docker apps to auto-start on container boot.\n\n## Getting Started\n\n### Prerequisites\n\nBefore using **lws**, ensure you have the following:\n\n- **Python 3.6+**: Required to run **lws**.\n- **Proxmox VE**: **lws** is designed to work with Proxmox Virtual Environment.\n- **SSH Access**: **lws** uses SSH to interact with Proxmox hosts and LXC containers.\n- **Pip**: Python's package installer.\n\n### Installation\n\n1. **Clone the Repository**\n   ```bash\n   git clone https://github.com/fabriziosalmi/lws.git\n   cd lws\n   ```\n\n2. **Install Dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Make lws Executable**\n   ```bash\n   chmod +x lws.py\n   ```\n\n4. **Create a Shortcut**\n   ```bash\n   alias lws='./lws.py'\n   ```\n\n5. **Verify Installation**\n   ```bash\n   lws --help\n   ```\n\n### Configuration\n\n**lws** is configured using a `config.yaml` file. This file defines your environment settings, including regions, availability zones (AZs), instance sizes, network settings, security credentials, and ng parameters.\n\n#### Example `config.yaml`\n\n```yaml\nuse_local_only: false\nstart_vmid: 10000\ndefault_storage: local-lvm\ndefault_network: vmbr0\nminimum_resources:\n  cores: 1\n  memory_mb: 512\nregions:  \n  eu-south-1:\n    availability_zones:\n      az1:\n        host: proxmox1.public-fqdn.com     # example: public FQDN (access must be secured)\n        user: root\n        ssh_password: password\n      az2:\n        host: 172.23.0.2                   # example: VPN address\n        user: root\n        ssh_password: password\n      az3:\n        host: proxmox3.local               # example: local network\n        user: root\n        ssh_password: password\n      az4:\n        host: 192.168.0.4                  # example: LAN address\n        user: root\n        ssh_password: password\n\n  eu-central-1:\n    availability_zones:\n      pve-rhine:\n        host: pve-rhine.mydomain.com\n        user: root\n        ssh_password: password\n      pve-alps:\n        host: pve-alps.mydomain.com\n        user: root\n        ssh_password: password\n```\n\n\u003e [!IMPORTANT]\n\u003e Secure your `config.yaml` file to prevent exposure of sensitive information. Consider using tools like `ansible-vault` or environment variables for managing sensitive data securely.\n\n## Usage\n\n**lws** offers various commands for managing Proxmox VE, LXC containers, and Docker services. Below are detailed examples for each command set.\n\n### Proxmox Management\n\nManage your Proxmox hosts and clusters with these commands. Use the `--region` and `--az` options to target specific regions and availability zones.\n\n#### List all Proxmox hosts\n```bash\nlws px list\n```\n\u003e [!TIP]\n\u003e Use the `list` command to quickly verify which Proxmox hosts are available for management in specific regions.\n\n#### Backup configurations of a Proxmox host in a region\n```bash\nlws px backup --region eu-south-1\n```\n\n#### Backup a specific LXC container\n```bash\nlws px backup-lxc 101 --region eu-south-1 --az az1\n```\n\n#### Restart all cluster services in a specific AZ\n```bash\nlws px cluster-restart --region eu-central-1 --az pve-rhine\n```\n\n#### Create a template image from an LXC container\n```bash\nlws px image-add 101 --region eu-central-1 --az pve-alps --template-name \"my-template\"\n```\n\n#### Delete a template image from a specific AZ\n```bash\nlws px image-rm --region eu-central-1 --az pve-rhine --template-name \"my-template\"\n```\n\n\u003e [!WARNING]\n\u003e Be careful when deleting images, as this action is irreversible and can result in data loss.\n\n#### Monitor resource usage of a Proxmox host\n```bash\nlws px status --region eu-south-1 --az az3\n```\n\n#### Reboot a Proxmox host in a specific AZ\n```bash\nlws px reboot --region eu-south-1 --az az2\n```\n\n\u003e [!TIP]\n\u003e Rebooting a Proxmox host will temporarily affect all services running on it. Ensure you plan this operation during maintenance windows.\n\n### LXC Container Management\n\nManage LXC containers with these versatile commands. Just specify the container ID and, optionally, the region and AZ.\n\n#### Start an LXC container\n```bash\nlws lxc start 101 --region eu-central-1 --az pve-alps\n```\n\n#### Stop a running LXC container\n```bash\nlws lxc stop 101 --region eu-central-1 --az pve-alps\n```\n\n#### Reboot an LXC container\n```bash\nlws lxc reboot 101 --region eu-central-1 --az pve-alps\n```\n\n#### Terminate (destroy) an LXC container\n```bash\nlws lxc terminate 101 --region eu-central-1 --az pve-alps\n```\n\n\u003e [!WARNING]\n\u003e The `terminate` command permanently deletes the LXC container. Use this with caution.\n\n#### Clone an LXC container locally or remotely\n```bash\nlws lxc clone 101 102 --region eu-central-1 --az pve-alps\n```\n\n#### Migrate an LXC container between AZs\n```bash\nlws lxc migrate 101 --region eu-central-1 --source-az pve-rhine --target-az pve-alps\n```\n\n#### Execute a command inside an LXC container\n```bash\nlws lxc exec 101 --region eu-central-1 --az pve-alps --command \"apt-get update\"\n```\n\n#### Scale resources of an LXC container\n```bash\nlws lxc scale 101 --region eu-central-1 --az pve-alps --cpu 4 --memory 8192\n```\n\n\u003e [!TIP]\n\u003e Scaling resources can help optimize performance but may also increase resource consumption on your host.\n\n#### Create a snapshot of an LXC container\n```bash\nlws lxc snapshot-add 101 --region eu-central-1 --az pve-alps --name \"pre-update\"\n```\n\n#### List all snapshots of an LXC container\n```bash\nlws lxc show-snapshots 101 --region eu-central-1 --az pve-alps\n```\n\n#### Attach a storage volume to an LXC container\n```bash\nlws lxc volume-attach 101 --region eu-central-1 --az pve-alps --volume \"my-volume\"\n```\n\n#### Retrieve the public IP address of an LXC container\n```bash\nlws lxc show-public-ip 101 --region eu-central-1 --az pve-alps\n```\n\n### Docker Management\n\nManage Docker services within LXC containers using these commands. Specify the container ID along with the region and AZ.\n\n#### Install Docker and Compose on an LXC container\n```bash\nlws app setup 101 --region eu-south-1 --az az1\n```\n\n#### Deploy a Docker Compose application\n```bash\nlws app deploy 101 --region eu-south-1 --az az1 --compose-file docker-compose.yml\n```\n\n\u003e [!TIP]\n\u003e Ensure your `docker-compose.yml` file is correctly configured before deployment to avoid runtime issues.\n\n#### List Docker containers in an LXC container\n```bash\nlws app list 101 --region eu-south-1 --az az1\n```\n\n#### Fetch Docker logs from an LXC container\n```bash\nlws app logs 101 --region eu-south-1 --az az1 --container \"my-container\"\n```\n\n#### Update an app within an LXC container via Compose\n```bash\nlws app update 101 --region eu-south-1 --az az1\n```\n\n\u003e [!TIP]\n\u003e Regularly updating your Docker containers ensures they are running the latest versions with security patches.\n\n### Client Configuration Management\n\nManage your **lws** client configurations with these commands.\n\n#### Backup the current configuration to a file\n```bash\nlws conf backup --output backup-config.yaml\n```\n\n#### Show the current configuration\n```bash\nlws conf show\n```\n\n#### Validate the current configuration\n```bash\nlws conf validate\n```\n\n\u003e [!IMPORTANT]\n\u003e Always validate your configuration after making changes to avoid runtime errors.\n\n### Managing Instance Profiles\n\nInstance profiles define the resource allocations (memory, CPU, storage) for different types of workloads. These can be customized for specific applications, ranging from general-purpose to specialized setups.\n\n#### Example Instance Profiles\n\n```yaml\ninstance_sizes:\n  micro:\n    memory: 512 \n    cpulimit: 1 \n    storage: local-lvm:4  \n  small:\n    memory: 1024 \n    cpulimit: 1 \n    storage: local-lvm:8   \n  mid:\n    memory: 2048 \n    cpulimit: 2\n    storage: local-lvm:16  \n  large:\n    memory: 4096 \n    cpulimit: 2\n    storage: local-lvm:32   \n  x-large:\n    memory: 8192 \n    cpulimit: 4 \n    storage: local-lvm:64   \n  \n  # Specialized instance profiles for specific applications\n  lws-postgres:\n    memory: 4096  # 4 GB\n    cpulimit: 2   # 2 vCPUs\n    storage: local-lvm:40  # 40 GB of storage\n    # Example: PostgreSQL for relational database.\n\n  lws-redis:\n    memory: 2048  # 2 GB\n    cpulimit: 1   # 1 vCPU\n    storage: local-lvm:10  # 10 GB of storage\n    # Example: Redis for in-memory caching.\n```\n\n\u003e [!TIP]\n\u003e Customize instance profiles based on the specific requirements of your applications. For example, databases like PostgreSQL may need more memory and CPU, while caching solutions like Redis can operate efficiently with fewer resources.\n\n### Managing Security Settings\n\nSecurity settings within **lws** control aspects like SSH timeouts, discovery methods, and the number of parallel workers. These settings help secure your environment while ensuring efficient operations.\n\n#### Example Security Configuration\n\n```yaml\nsecurity:\n  discovery:\n    proxmox_timeout: 2  # Timeout in seconds for Proxmox host discovery\n    lxc_timeout: 2  # Timeout in seconds for LXC container discovery\n    discovery_methods: ['ping']  # Methods used for discovering resources\n    max_parallel_workers: 10  # Maximum number of parallel workers during discovery\n```\n\n\u003e [!TIP]\n\u003e Adjust the `max_parallel_workers` setting to optimize discovery operations based on your infrastructure's size and complexity.\n\n### Managing Scaling Thresholds and Triggers\n\nScaling thresholds and triggers allow **lws** to automatically adjust resources (CPU, memory, storage) for LXC containers based on defined conditions met on both the Proxmox host and the LXC container. This feature ensures optimal performance while preventing resource exhaustion.\n\n#### Example Scaling Configuration\n\n```yaml\nscaling:\n  host_cpu:\n    max_threshold: 80  # Maximum percentage of host CPU usage before scaling down\n    min_threshold: 30  # Minimum percentage of host CPU usage before scaling up\n    step: 1  # Base increment or decrement of CPU cores on the host\n    scale_up_multiplier: 1.5  # Multiplier applied to step size when scaling up\n    scale_down_multiplier: 0.5  # Multiplier applied to step size when scaling down\n\n  lxc_cpu:\n    max_threshold: 80  # Maximum percentage of LXC CPU usage before scaling down\n    min_threshold: 30  # Minimum percentage of LXC CPU usage before scaling up\n    step: 1  # Base increment or decrement of CPU cores in the LXC\n    scale_up_multiplier: 1.5  # Multiplier applied to step size when scaling up\n    scale_down_multiplier: 0.5  # Multiplier applied to step size when scaling down\n\n  host_memory:\n    max_threshold: 70  # Percentage of total memory on the host before scaling down\n    min_threshold: 40  # Percentage of total memory on the host before scaling up\n    step_mb: 256  # Base amount of memory in MB to increase or decrease\n    scale_up_multiplier: 1.25  # Multiplier applied to step size when scaling up\n    scale_down_multiplier: 0.75  # Multiplier applied to step size when scaling down\n\n  lxc_memory:\n    max_threshold: 70  # Maximum percentage of LXC memory usage before scaling down\n    min_threshold: 40  # Minimum percentage of LXC memory usage before scaling up\n    step_mb: 256  # Base amount of memory in MB to increase or decrease\n    scale_up_multiplier: 1.25  # Multiplier applied to step size when scaling up\n    scale_down_multiplier: 0.75  # Multiplier applied to step size when scaling down\n\n  host_storage:\n    max_threshold: 85  # Maximum percentage of storage usage on the host before scaling down\n    min_threshold: 50  # Minimum percentage of storage usage on the host before scaling up\n    step_gb: 10  # Base increment or decrement of storage in GB\n    scale_up_multiplier: 1.5  # Multiplier applied to step size when scaling up\n    scale_down_multiplier: 0.5  # Multiplier applied to step size when scaling down\n\n  lxc_storage:\n    max_threshold: 85  # Maximum percentage of storage usage in the LXC before scaling down\n    min_threshold: 50  # Minimum percentage of storage usage in the LXC before scaling up\n    step_gb: 10  # Base increment or decrement of storage in GB\n    scale_up_multiplier: 1.5  # Multiplier applied to step size when scaling up\n    scale_down_multiplier: 0.5  # Multiplier applied to step size when scaling down\n\n  limits:\n    min_memory_mb: 512  # Minimum allowed memory for any LXC container\n    max_memory_mb: 32768  # Maximum allowed memory for any LXC container\n    min_cpu_cores: 1  # Minimum allowed CPU cores for any LXC container\n    max_cpu_cores: 16  # Maximum allowed CPU cores for any LXC container\n    min_storage_gb: 10  # Minimum allowed storage for any LXC container\n    max_storage_gb: 1024  # Maximum allowed storage for any LXC container\n\n  general:\n    scaling_interval: 5  # Interval in minutes to check for resource adjustments\n    notify_user: true  # Notify user via CLI output when scaling adjustments are made\n    dry_run: false  # If true, simulate scaling adjustments without applying changes\n    scaling_log_level: DEBUG  # Log level for scaling operations (DEBUG, INFO, WARN, ERROR)\n    use_custom_scaling_algorithms: false  # Enable if custom scaling algorithms are implemented\n```\n\n\u003e [!TIP]\n\u003e Use `notify_user: true` to get immediate feedback on scaling adjustments, which is especially useful in dynamic environments.\n\n\u003e [!WARNING]\n\u003e Be cautious when setting the `dry_run` option to `false`, as real scaling adjustments will be applied. Ensure your thresholds and multipliers are well-tested before applying them in production.\n\n## Security Considerations\n\nGiven that **lws** involves sensitive operations and SSH connections, it's important to:\n\n- **Protect Your Configuration**: Ensure your `config.yaml` file is secure.\n- **Use in Non-Production Environments**: As **lws** is in its early stages, it's\n\n safer to use it in test or development environments.\n- **Use Secured Connections**: Always protect management communications with a VPN or similar secured connection.\n\n\u003e [!WARNING]\n\u003e Misconfigured SSH or insecure usage can lead to unauthorized access to your systems. Always follow best practices for SSH security.\n\n## Best Practices\n\n- **Regular Backups**: Regularly back up your configuration and important data.\n- **Testing Before Use**: Thoroughly test **lws** commands in a non-production environment before applying them to critical systems.\n- **Keep Updated**: Keep your **lws** installation and dependencies updated to benefit from the latest features and fixes.\n\n## Contributing\n\n**lws** is an open-source project developed for fun and learning. Contributions are welcome! Feel free to submit issues, feature requests, or pull requests.\n\n### How to Contribute\n\n1. **Fork the Repository**\n2. **Create a Branch**\n   ```bash\n   git checkout -b feature-branch\n   ```\n3. **Make Changes**\n4. **Submit a Pull Request**\n\n\u003e [!TIP]\n\u003e Include clear commit messages and documentation with your pull requests to make the review process smoother.\n\n## Roadmap\n\n**lws** is still in its infancy. Planned features and improvements include:\n\n- **Improved Error Handling**: More robust error handling and feedback mechanisms.\n- **Additional Commands**: Expanding the set of management commands.\n- **User Interface Improvements**: Enhanced user experience with better output formatting and additional CLI options.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n## Acknowledgements\n\n- **Proxmox VE**: The powerful virtualization platform that inspired this project.\n- **LXC**: For making Linux containers a reality.\n- **Docker**: For making container management simpler and more efficient.\n- **Open Source Community**: For the tools and libraries that made this project possible.\n\n---\n\n\u003e [!WARNING]\n\u003e **Disclaimer**: **lws** is a project created for fun and exploration. It is not intended for production use, and users should exercise caution when using it on live systems. Always test thoroughly in a non-production environment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziosalmi%2Flws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabriziosalmi%2Flws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziosalmi%2Flws/lists"}