{"id":13394770,"url":"https://github.com/typicode/katon","last_synced_at":"2025-04-12T18:49:57.619Z","repository":{"id":13821009,"uuid":"16517540","full_name":"typicode/katon","owner":"typicode","description":"(use hotel instead)","archived":false,"fork":false,"pushed_at":"2019-12-13T23:40:07.000Z","size":315,"stargazers_count":683,"open_issues_count":12,"forks_count":28,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-10-29T23:22:56.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/typicode/hotel","language":"JavaScript","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/typicode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-04T16:25:46.000Z","updated_at":"2024-09-19T04:05:04.000Z","dependencies_parsed_at":"2022-09-03T10:11:00.952Z","dependency_job_id":null,"html_url":"https://github.com/typicode/katon","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typicode%2Fkaton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typicode%2Fkaton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typicode%2Fkaton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typicode%2Fkaton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typicode","download_url":"https://codeload.github.com/typicode/katon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174456,"owners_count":20896078,"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":[],"created_at":"2024-07-30T17:01:31.004Z","updated_at":"2025-04-04T12:10:32.152Z","avatar_url":"https://github.com/typicode.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# katon [![](https://badge.fury.io/js/katon.svg)](http://badge.fury.io/js/katon) [![](https://travis-ci.org/typicode/katon.svg?branch=master)](https://travis-ci.org/typicode/katon)\n\n---\n\n__Note__ except if you need a particular feature in katon, please use [hotel](https://github.com/typicode/hotel). Hotel is cross-platform and doesn't require admin privileges to be installed.\n\nA huge thank you to all the [people](https://github.com/typicode/katon/graphs/contributors) who contributed to katon!\n\n---\n\n\u003e Access your dev servers by their names\n\nkaton is a development tool that makes dev servers __accessible__ on __beautiful__ local .ka domains. It also __autostarts/stops__ them for you.\n\n![](http://i.imgur.com/AyFpCHj.png)\n\nkaton supports any server: __Node, Ruby, Python, Go, Java, PHP, ...__ that can be started with a command-line and runs on __OS X__.\n\n### Linux, Windows\n\nPlease use [hotel](https://github.com/typicode/hotel).\n\n## Install\n\nMake sure [Node](http://nodejs.org/download/) is installed first, then:\n\n```bash\n$ npm install -g katon\n```\n\nTo manually install katon, you can run `sudo katon install \u0026\u0026 katon start`.\n\n_Known issue: if Apache is running, it needs to be stopped to avoid conflict with katon._\n\n## Add servers\n\n```bash\n$ katon add 'nodemon'\n$ katon add 'npm start'\n$ katon add 'grunt server'\n$ katon add 'rails server --port $PORT'\n$ katon add 'python -m SimpleHTTPServer $PORT'\n$ katon add 'php -S 127.0.0.1:$PORT'\n```\n\nTo add a server with a different name than its directory.\n\n```bash\n$ katon add 'grunt server' my-custom-name\nApplication is now available at http://my-custom-name.ka\n```\n\n__Note__: it's important to use `'` and not `\"` to avoid `$PORT` to be evaluated.\n\nPort is dynamically set by katon using `PORT` environment variable but can be passed as a parameter using `$PORT`.\n\nIn case your server doesn't accept a port parameter, you can retrieve the `PORT` environment variable in your code. For example, for a Node server you would write something like:\n\n```javascript\nvar port = process.env.PORT || 3000;\n```\n\nThe same technique can be applied with other languages too.\n\n## How it works\n- When you add a server using the `katon add` command, its configuration is saved locally to `~/.katon/hosts/\u003capp\u003e` and an equivalent `~/.katon/logs/\u003capp\u003e` directory is also created.\n- The server is not started until you make your first request to your `\u003capp\u003e.ka` domain.\n- If no request is made to your `\u003capp\u003e.ka` server within an hour, then katon automatically stops it. Therefore, Katon automatically manages resources by starting only needed servers and stopping them when they're not used.\n\n## Subdomains\n\nWhen adding a server, you can access it by its URL `http://app.ka`. But you can also use subdomains (e.g. `http://foo.app.ka`, `http://bar.app.ka`, ...).\n\nIf you want to map a server to a subdomain, let's say `api.app.ka`, simply use `katon add \u003ccmd\u003e api.app`.\n\n## Access from other devices\n\nUsing [xip.io](http://xip.io/) you can access your servers from other devices (iPad, iPhone, ...) on your LAN.\n\n```\n# Let's say your local address is 192.168.1.12\nhttp://\u003capp_name\u003e.192.168.1.12.xip.io/\n```\n\n_You can find your local address using `ifconfig` or going to index.ka_\n\n## Remote access behind NAT/firewall\n\nUsing [ngrok.com](http://ngrok.com/) you can share access to your servers with others, when running behind a firewall or NAT.\n\nFirst, follow the instructions to install ngrok, then [register on the site](https://dashboard.ngrok.com/user/signup) to enable custom subdomains.\n\nThen run ngrok with your application name as the subdomain:\n\n```\nngrok http -subdomain app_name 80\n```\n\nThis exposes port 80 to the internet on *app_name.ngrok.io*. **Use at your own risk: all of your web hosts are accessible on this port while ngrok is running.**\n\n## Access using HTTPS\n\nYou can also use HTTPS to access your servers `https://\u003capp_name\u003e.ka`.\n\n## Logs\n\nServer logs are stored in `~/.katon/logs/\u003capp_name\u003e.log`, to view them you can use:\n\n```bash\n$ katon tail [app_name]\n$ katon tail all # View all logs\n```\n\n## Version managers\n\nkaton works with any version manager, simply set the desired version before adding your server and katon will remember it.\n\n```bash\n$ nvm use 0.11 \u0026\u0026 katon add 'npm start'\n$ rbenv local 2.0.0-p481 \u0026\u0026 katon add 'rails server --port $PORT'\n```\n\nDepending on your version manager, you may need to add environment variables.\n\n```bash\n$ rvm use ruby-2.0.0-p576 \u0026\u0026 katon add 'bundle exec unicorn' --env GEM_PATH\n# Will use GEM_PATH previously set by rvm\n```\n\nFor Node users, to keep access to katon CLI accross Node versions, add an alias to your .profile and reopen the Terminal.\n\n```bash\necho \"alias katon=`which katon`\" \u003e\u003e ~/.profile\n```\n\n## Troubleshoot\n\nRun `katon status` or check `~/.katon/daemon.log`.\n\nIf you're stuck, feel free to create an issue.\n\n## Uninstall\n\n```bash\n$ npm rm -g katon\n```\n\nThis will run the uninstall script wich does basically `katon stop \u0026\u0026 sudo katon uninstall`. To remove katon completely, run also `rm -rf ~/.katon`.\n\n# Credits\n\n* [Pow](http://pow.cx/) for daemon inspiration.\n* [Powder](https://github.com/rodreegez/powder) for CLI inspiration.\n\n# License\n\nkaton is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypicode%2Fkaton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypicode%2Fkaton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypicode%2Fkaton/lists"}