{"id":15110251,"url":"https://github.com/acryps/vlcluster","last_synced_at":"2026-01-18T22:34:07.191Z","repository":{"id":55065098,"uuid":"313661928","full_name":"acryps/vlcluster","owner":"acryps","description":"Scaleable distributed cluster based on Docker Containers","archived":false,"fork":false,"pushed_at":"2023-09-13T09:32:37.000Z","size":493,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-22T02:25:56.159Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acryps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-11-17T15:29:00.000Z","updated_at":"2022-08-01T12:02:34.000Z","dependencies_parsed_at":"2024-09-20T18:10:57.064Z","dependency_job_id":"aec100b6-402d-49f9-b890-34d7e387722b","html_url":"https://github.com/acryps/vlcluster","commit_stats":null,"previous_names":["levvij/vlcluster"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/acryps/vlcluster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acryps%2Fvlcluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acryps%2Fvlcluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acryps%2Fvlcluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acryps%2Fvlcluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acryps","download_url":"https://codeload.github.com/acryps/vlcluster/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acryps%2Fvlcluster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28552786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T20:59:07.572Z","status":"ssl_error","status_checked_at":"2026-01-18T20:59:02.799Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-09-25T23:43:12.783Z","updated_at":"2026-01-18T22:34:07.173Z","avatar_url":"https://github.com/acryps.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](http://badge.acryps.com/npm/vlcluster)](http://badge.acryps.com/go/npm/vlcluster)\n\n# vlcluster\nSimple docker and nginx-based cluster designed for multi-env web applications.\n\n\u003e vlcluster is currently beeing restructured\n\n\u003cimg width=\"100%\" src=\"doc/overview.svg\"\u003e\n\n# Getting Started\nvlcluster consists of four different node types\n- `registry` Manages the cluster; stores and delivers applications\n- `worker`s Run `instance`s of applications\n- `gateway`s Create nginx-proxys to `instance`s running in `worker`s\n- `client` Developers; can manage the cluster and push new applications\n\nYou can put multiple different node types on the same computer\n\n## Setting up the cluster\nYou can use windows, macOS or linux to manage your cluster and uplaod new application, but the `registry`, `workers` and `gateways` require linux with `systemd` (ubuntu, centos, fedora, ...)!\n\n### Creating the registry\nRun the following commands to create our first registry. We'll call it **mainnet**. You can only have one registry per cluster - but you can have multiple clusters and switch between them! Make sure that your registry has a static ip address or a DNS entry, we'll need it later on to reference the node!\n\u003cpre\u003e\nsudo npm install -g vlcluster\nsudo vlcluster init registry -n \"\u003cb\u003emainnet\u003c/b\u003e\"\n\u003c/pre\u003e\n\nThis will create the registry in `~/.vlcluster`. The command will return a **key**. This key will be used later on to create the workers and clients\n\u003cpre\u003e\ncreated registry!\n\nprivate key: \u003cb\u003e8cfh8jVXPd...\u003c/b\u003e\nStore this key safely!\n\u003c/pre\u003e\n\nWe need to make sure that vlcluster runs, even after a reboot. So, let's install it as a `systemd` service!\n```\nsudo vlcluster daemon install -u root\n```\n\n### Setting up our first worker\nNow you can either switch to a new machine or install the worker and the registry on the same machine. Run the following commands to create a worker and assign it a `endpoint` address.\n\u003cpre\u003e\n# install packages\nsudo apt install docker.io # install docker (if you don't already have it)\nsudo npm install -g vlcluster\n\n# create worker\nsudo vlcluster init worker -n \"worker1\" -h \u003cb\u003eregistry.example.com\u003c/b\u003e -k \u003cb\u003e8cfh8jVXPd4...\u003c/b\u003e -e \u003cb\u003eworker1.example.com\u003c/b\u003e\n\u003c/pre\u003e\n\nWe have to restart the daemon if your worker is *on the same node as the registry*. \n```\nsudo service vlcluster restart\n```\n\nIf you're using a different node, install the vlcluster daemon with `systemd`\n```\nsudo vlcluster daemon install -u root\n```\n\n### Creating a gateway\nWe want our requests to be able to get to our `instance`s, so let's setup the gateway. You can do this on the same node as your `worker` or `registry`!\n\u003cpre\u003e\n# install packages\nsudo apt install nginx\nsudo npm install -g vlcluster\n\n# create gateway\nsudo vlcluster init gateway --name \"gateway1\" --cluster-hostname \u003cb\u003eregistry.example.com\u003c/b\u003e --cluster-key \u003cb\u003e8cfh8jVXPd4...\u003c/b\u003e --endpoint-hostname \u003cb\u003egateway1.example.com\u003c/b\u003e\n\u003c/pre\u003e\n\nRestart the vlcluster daemon or install the daemon with `systemd`, like we did with the worker!\n\n### Connecting to the cluster\nLet's get our first app published on our new **mainnet** cluster!\n\nFirst, let's create a `client`. Open a new terminal on your computer and type\n```\nnpm install -g vlcluster\nvlcluster init\n```\n\nNow enter your email, the hostname of our registry (`registry.example.com` in the example) and paste the key (`8cfh8jVXPd4...` in our example).\n\n\u003e You need to have docker installed on your system → [Installation page](https://docs.docker.com/get-docker/)\n\nYou don't need to run vlcluster as a daemon on your client.\n\n### Setting up applications\nClone [vlcluster example](https://github.com/levvij/vlcluster-example) and open a terminal in the project directory\n\u003e Every vlcluster application requires a simple `Dockerfile` and a `package.json` with `name` and `version`\n\nWe'll deploy the `vlcluster-example` application to our registry, with the `env` **productive**.\n\n\u003cpre\u003e\nvlcluster deploy -c mainnet -e \u003cb\u003eproductive\u003c/b\u003e\n\u003c/pre\u003e\n\nWe want to reach the application, right? Let's route your domain name (`example-application.example.com:80` in this example) to the `vlcluster-example` application - but only to instances running as **productive**.\n\n\u003cpre\u003e\nvlcluster route domain -c \u003cb\u003emainnet\u003c/b\u003e -h \u003cb\u003eexample-application.example.com\u003c/b\u003e -p \u003cb\u003e80\u003c/b\u003e -a \u003cb\u003evlcluster-example\u003c/b\u003e -e \u003cb\u003eproductive\u003c/b\u003e\n\u003c/pre\u003e\n\n`example-application.example.com` will automatically be routed to the latest version of `vlcluster-example` running as `productive`.  A simple deploy is all you need now! vlcluster will install the new version, await application start up, update the proxies and then stop the old instances - zero downtime deploys!\n\nImagine you'd wanna run a \u003cb\u003etest\u003c/b\u003e environnement, and have it available on `test.example-application.example.com`. All you'll have to do is just type in those commands:\n\u003cpre\u003e\nvlcluster deploy -c mainnet -e \u003cb\u003etest\u003c/b\u003e\nvlcluster route domain -c mainnet -h \u003cb\u003etest.example-application.example.com\u003c/b\u003e -p 80 -a vlcluster-example -e \u003cb\u003etest\u003c/b\u003e\n\u003c/pre\u003e\n\n**When making your own application, make sure to listen on the port defined in the env variable `PORT`. The port will automatically be assigned and routed.**\n\n### Variables\nNobody wants hardcoded database connection strings! Thats why vlcluster allows you to create variables which will be set as ENV-variables in your applications\n\nJust run:\n\u003cpre\u003e\n# set variable for instances of \u003cu\u003eall\u003c/u\u003e applications in \u003cu\u003eall\u003c/u\u003e environnements\nvlcluster var set -c mainnet -n \u003cb\u003eDATABASE_HOST\u003c/b\u003e -v \u003cb\u003edata.example.com\u003c/b\u003e -a -e\n\n# set variable for instances of \u003cu\u003evlcluster-example\u003c/u\u003e in \u003cu\u003eall\u003c/u\u003e environnements\nvlcluster var set -c mainnet -n \u003cb\u003eDATABASE_USER\u003c/b\u003e -v \u003cb\u003eexample\u003c/b\u003e -a \u003cb\u003evlcluster-example\u003c/b\u003e -e\n\n# set variable for instances of \u003cu\u003evlcluster-example\u003c/u\u003e in \u003cu\u003etest\u003c/u\u003e and \u003cu\u003eproductive\u003c/u\u003e environnements\nvlcluster var set -c mainnet -n \u003cb\u003eDATABASE_NAME\u003c/b\u003e -v \u003cb\u003eexample\u003c/b\u003e -a \u003cb\u003evlce_db_prod\u003c/b\u003e -e \u003cb\u003eproductive\u003c/b\u003e\nvlcluster var set -c mainnet -n \u003cb\u003eDATABASE_NAME\u003c/b\u003e -v \u003cb\u003eexample\u003c/b\u003e -a \u003cb\u003evlce_db_test\u003c/b\u003e -e \u003cb\u003etest\u003c/b\u003e\n\u003c/pre\u003e\n\nThe variables will be set after a `deploy` or a `vlcluster instance restart`\n\n# Command Reference\n## Setup\n```\nvlcluster init [client] [-e | --email \u003cemail\u003e] [-h | --hostname \u003cregistry hostname\u003e] [-k | --key \u003cregistry key\u003e]\nvlcluster init registry [-n | --name \u003cregistry name\u003e]\nvlcluster init worker [-h | --hostname \u003cregistry hostname\u003e] [-k | --key \u003cregistry key\u003e] [-n | --name \u003cworker name\u003e] [-e | --endpoint \u003cworker endpoint\u003e]\nvlcluster init gateway [-h | --hostname \u003ccluster hostname\u003e] [-key | --key \u003ccluster key\u003e] [-n | --name \u003cgateway name\u003e] [-e | --endpoint \u003cendpoint hostname\u003e]\n\nvlcluster daemon install [-u | --user \u003cuser\u003e]\n```\n\n## Building and Publishing\n```\nvlcluster build [[ -p | --project-path ] \u003cproject path\u003e = \".\"]\nvlcluster push [-c | --cluster \u003cregistry hostname\u003e] [[ -a | --application ] \u003capplication\u003e] [[ -v | --version ] \u003cversion\u003e]\nvlcluster upgrade [-c | --cluster \u003cregistry hostname\u003e] [[ -a | --application ] \u003capplication\u003e] [[ -v | --version ] \u003cversion\u003e] [[ -e | --env ] \u003cenvironnement\u003e] [-i | --instances \u003cinstance count\u003e]\n\nvlcluster deploy [-c | --cluster \u003cregistry hostname\u003e] [[ -e | --env ] \u003cenvironnement\u003e] [[ -p | --project-path ] \u003cproject path\u003e = \".\"] [-i | --instances \u003cinstance count\u003e]\n```\n\n## Variables\n```\nvlcluster var set [-c | --cluster \u003cregistry hostname\u003e] [[ -n | --name ] \u003cname\u003e] [[ -v | --value ] \u003cvalue\u003e] [-a | --application [ \u003capplication\u003e ]] [-e | --env [ \u003cenvironnement\u003e ]]\nvlcluster var read [-c | --cluster \u003cregistry hostname\u003e] [[ -s | --source ] \u003cpath\u003e] [[ -v | --value ] \u003cvalue\u003e] [-a | --application [ \u003capplication\u003e ]] [-e | --env [ \u003cenvironnement\u003e ]]\nvlcluster var list [-c | --cluster \u003cregistry hostname\u003e] [-a | --application [ \u003capplication\u003e ]] [-e | --env [ \u003cenvironnement\u003e ]]\n```\n\n## Instance Management\n```\nvlcluster instance list [-c | --cluster \u003cregistry hostname\u003e] [-a | --application [ \u003capplication\u003e ]] [-e | --env [ \u003cenvironnement\u003e ]]\nvlcluster instance restart [-c | --cluster \u003cregistry hostname\u003e] [-a | --application [ \u003capplication\u003e ]] [-e | --env [ \u003cenvironnement\u003e ]]\n```\n\n## Routing\n```\nvlcluster route domain [-c | --cluster \u003cregistry hostname\u003e] [-h | --host \u003chost\u003e] [-p | --port \u003cport\u003e] [-a | --application \u003capplication\u003e] [-h | --host \u003chost\u003e] [-e | --env \u003cenv\u003e]\nvlcluster route websocket [-c | --cluster \u003cregistry hostname\u003e] [-h | --host \u003chost\u003e] [-p | --port \u003cport\u003e] [-l | --location \u003clocation\u003e]\n```\n\n## SSL \nSSL certificates are created by [certbot](https://certbot.eff.org/) which needs to be installed on the gateways!\nCreating the certificates requires the gateway to shutdown the nginx webserver temporarely!\n```\nvlcluster ssl enable [-c | --cluster \u003cregistry hostname\u003e] [-h | --host \u003chost\u003e] [-p | --port \u003cport\u003e]\n```\n\n## Utitlity\n```\nvlcluster system # shows cluster system info\nvlcluster daemon # runs vlcluster daemon\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facryps%2Fvlcluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facryps%2Fvlcluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facryps%2Fvlcluster/lists"}