{"id":25493734,"url":"https://github.com/kaydomrose/clocker","last_synced_at":"2025-08-24T09:14:04.485Z","repository":{"id":39442353,"uuid":"262542778","full_name":"KayDomrose/clocker","owner":"KayDomrose","description":"A tool to create a docker-ready server and deploy your compose-file project in seconds.","archived":false,"fork":false,"pushed_at":"2023-01-06T06:41:06.000Z","size":901,"stargazers_count":3,"open_issues_count":21,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T01:11:02.522Z","etag":null,"topics":["deploy","digitalocean","docker","docker-compose","droplet","hetzner-cloud","terraform"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/KayDomrose.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-09T10:08:29.000Z","updated_at":"2020-07-28T09:01:47.000Z","dependencies_parsed_at":"2023-02-05T13:31:54.614Z","dependency_job_id":null,"html_url":"https://github.com/KayDomrose/clocker","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KayDomrose%2Fclocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KayDomrose%2Fclocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KayDomrose%2Fclocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KayDomrose%2Fclocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KayDomrose","download_url":"https://codeload.github.com/KayDomrose/clocker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137888,"owners_count":21053775,"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":["deploy","digitalocean","docker","docker-compose","droplet","hetzner-cloud","terraform"],"created_at":"2025-02-18T23:17:15.454Z","updated_at":"2025-04-10T01:11:43.528Z","avatar_url":"https://github.com/KayDomrose.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clocker - CLoud doCKER\nclocker is a command line tool, that help you to set up remote server and deploy your docker-compose file with just a few commands.\n\n```shell script\n// Register a new cloud hoster like DigitalOcean with your access token\nclocker hoster register\n\n// Create a server \u003cmy-server\u003e\nclocker add\n\n// Create a new server based on configuration and provision it, ready for docker \nclocker start \u003cmy-server\u003e\n\n// Deploy your project to the server. Exposed ports are reachable via server ip \nclocker deploy \u003cmy-server\u003e ./docker-compose.yml\n```\n\nYou can set up a new server in minutes, without any manual server configuration, destroy and re-create it anytime you need.\n\nIt's ideal for you if you  \n- need a small service online every now and then without setting up a server every time or paying for a server you don't use or that is not running.\n- want a place to quickly showcase a project in a more realistic environment.\n- have a small budget or no experience in server administration but want your work online.\n\nclocker exposes all the magic it does in terraform templates and docker commands.  \nWhen you want to get more professional, you can use this as a starting point for a more advanced provisioning.\n\n## ❗Do not use in production❗️\nThis project is in a very early stage and just a proof of concept for now.\n\nIt sure has many bugs and design flaws that will destroy your deployed project without backup or recovery.\n\nOnly the minimal happy path is working for now.\n\n## TOC\n1. [Overview](#Overview)\n2. [Supported providers](#Supported-providers)\n3. [Installation](#Installation)\n4. [Usage](#Usage)\n5. [Limitations \u0026 Known Problems](#Limitations-\u0026-Known-Problems)\n6. [Development](#Development)\n7. [Intention \u0026 Goals](#Intention-\u0026-Goals)\n8. [License](#License)\n\n## Overview\nSee below for more details on how to [install](#Installation) and [use](#Usage) clocker.\n\n### Step 1: Register a hoster\n```shell script\nclocker hoster register\n```\n![Clocker hoster register step](./docs/assets/readme-hoster-register.png)\n\n### Step 2: Configure a new server\n```shell script\nclocker add\n```\n![Clocker add step](./docs/assets/readme-add.png)\n\n### Step 3: Start your server\n```shell script\nclocker start my-test-server\n```\n![Clocker start step](./docs/assets/readme-start.png)\n\n### Step 4: Deploy your project\n```shell script\nclocker deploy my-test-server ./test/docker-compose.test.yml \n```\n![Clocker deploy step](./docs/assets/readme-deploy.png)\n\n### Step 5: Check server\n```shell script\nclocker list\n```\n![Clocker start step](./docs/assets/readme-list.png)\n\n## Supported providers\n- [DigialOcean](https://www.digitalocean.com/)\n- [Hetzner Cloud](https://www.hetzner.com/cloud)\n\n### Planed \n- AWS [#2](https://github.com/KayDomrose/clocker/issues/2)\n\n## Installation\n\n### Supported OS\nclocker is only tested on macOS yet.\n\nLinux may also be supported, as clocker only uses terraform, docker and some basic commands under the hood.\n\n\n### Prerequisites \nThese tools need to be installed and executable in your cli:\n- [Node \u0026 NPM](https://nodejs.org/en/)  \n`npm -v`\n- [Terraform](https://learn.hashicorp.com/terraform/getting-started/install)   \n`terraform -v`\n- [Docker](https://docs.docker.com/desktop/)  \n`docker -v`\n\n### Install clocker\n```shell script\nnpm install -g @kay.domrose/clocker\n```\n\n## Usage\nclocker is designed to run from anywhere in your cli, so you don't need a special folder or something.\n\nYou can always add `--verbose` to any command to see in detail what clocker is doing or more information about errors. \n\n### Initialize clocker\nBefore you can use clocker, it has to be initialized.  \nIn your favorite cli, run: \n```shell script\nclocker init\n```\n\nThis will create a `.clocker` folder in your home directory, where clocker stores stuff about your hosters and servers.\n\n### List all configured hosters with servers\nYou can get an overview of all hosters and servers configured, whether they are running or not and which projects have been deployed.\n```shell script\nclocker list\n```\n\n### Register a hoster\nFirst of all you need to register a hoster. This is like an local instance of your cloud server provider and will register some remote resources like your ssh key.  \nThat way you can easily add multiple server to the same hoster.\n```shell script\nclocker hoster register\n```\nA configuration wizard will ask you which cloud server provider you want to use and some questions based on your choice. After that, some resources will be created via terraform.  \nThere is no server created yet.\n\nYou can see all files that are created for your hoster in `.clocker/hosters/\u003cyour-hoster-id\u003e` in your home directory.\n\n### Add a server\n```shell script\nclocker add\n```\nAnother wizard will ask you some questions about which of your registered hoster you want to use and other configuration about the server.  \n**Nothing will be actually created yet**, so its save to play around.\n\nUnder the hood, we use terraform to create templates on how your server should look like.  \nYou can see all files that are created for your server in `.clocker/servers/\u003cyour-server-id\u003e` in your home directory.\n\n### Start a server\nAfter you've added a server, it's time to start it: \n```shell script\nclocker start \u003cyour-server-id\u003e\n```\n\nThis will use the terraform templates mentioned above to:\n1. Create a fresh server at your cloud provider of choice.\n2. Provision the server once created:\n    1. Install docker, vim, nginx\n    2. Create a `worker` user, which is used to interact with the server (instead of root)\n    3. Deploy a docker test container to check whether the server is ready or not (`http://\u003cserver-ip\u003e:11111`)\n\nClocker will prompt you the ip of your new server once its created and provisioned successfully.\n    \nYou can also access the server manually via ssh by running `ssh worker@\u003cserver-ip\u003e`.     \n \n ### Deploy a docker-compose file\nclockers main purpose is to easily deploy your local docker-compose project to a remove server.  \nBefore you do so, check the [limitations section](#Limitations) for potential problems.\n \nIf you don't have a docker-compose file ready or just want to try clocker, you can use [this docker-compose file](https://github.com/KayDomrose/clocker/blob/master/tests/docker-compose.test.yml) for a test.\n\nMake sure your server is running, then run: \n```shell script\nclocker deploy \u003cyour-server-id\u003e \u003cpath-to-your-docker-compose-file\u003e\n```\nAny service in your compose file, that exposes a port, can be accessed with your server ip: `http://\u003cserver-ip\u003e:\u003cexposed-port\u003e`.  \nIn the docker-compose file mentioned above, the service exposes port 7000, so you can access it in your browser `http://\u003cserver-ip\u003e:7000`. \n \n### Stop a server\nAs most cloud server providers will still charge you even when the server is not running, clocker will instead destroy the server and create a new one when you need it again.\n\nTo stop a running server, run: \n```shell script\nclocker stop \u003cyour-server-id\u003e\n```\n\n### Remove a server\nIf you want to completely remove a server in clocker, run: \n\n```shell script\nclocker remove \u003cmy-server-id\u003e\n```\n\n### Unregister a hoster\nYou can remove a hoster from clocker once all servers for that are removed by running:\n```shell script\nclocker hoster unregister \u003cmy-hoster-id\u003e\n```\nThis will destroy resources created via terraform from this cloud server provider and delete the local hoster directory.\n\n### Customize / Eject\nclocker saves all configuration it needs to work with your server in a single directory at `.clocker/servers/\u003cyour-server-ip\u003e`, including the terraform state.  \nThere is nothing hidden elsewhere, so feel free to explore.\n\nThe main idea of clocker is to give you a good kickstart for new projects, you want to deploy, but also give you anything you need to customize the basic setup.\n\nIf you want to modify or extend your server configuration, run\n```shell script\nclocker eject \u003cmy-server-id\u003e \u003ctarget-path\u003e\n```\nclocker will move all necessary files to your target directory, including terraform template, variables and state. Now you can change these configurations and clocker will not overwrite them.  \nYou can't manage this server via clocker anymore, but can run the terraform commands yourself.\n \n\n## Limitations \u0026 Known Problems\n1. There is no persistent storage (yet) to store files created or used in your docker-compose. [#8](https://github.com/KayDomrose/clocker/issues/8)\n2. Multiple compose files deployed to the same server may use same ports.\n\n## Development\n1. Clone repo\n2. Install dependencies `npm install` (you also need Terraform and Docker)\n3. Create environment `cp .env.example .env` and configure\n4. Run clocker commands `npm run command ARGS -- FLAGS`.  \nFor example:`npm run command init`.  \nTo add flags, add them at the end, separated by ` -- ` (e.g. `npm run command init -- --verbose`).\n\nAfter you are done with your work, run `npm run build` to create a test-build. This will be linked with npm (`npm link`), so you can use clocker as you would normally do (`clocker ARGS`).\n\n## Intention \u0026 Goals\nSetting up a remote server to run a dockerized project can be difficult and hard to work out, especially for inexperienced developers, who just want to see their project running.\n\nBy automatising the server provisioning with a default docker environment, this project can help you to easily spin up a remote server and deploy your project, ready to be used, in just a few clicks.  \n\nIt is by no means a professional tool to run your production application on.\n\nThere is no magic going on. Under the hood, clocker uses terraform and docker-cli to create, provision and deploy. \n\n\n## License\nclocker is [MIT licensed](https://github.com/KayDomrose/clocker/blob/master/LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaydomrose%2Fclocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaydomrose%2Fclocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaydomrose%2Fclocker/lists"}