|
| 1 | +# Kuda Web Server |
| 2 | + |
| 3 | +[](https://opensource.org/licenses/MIT) |
| 4 | +[](https://github.com/Thor-x86/kuda/issues) |
| 5 | +[](https://github.com/Thor-x86/kuda/pulls) |
| 6 | +[](https://travis-ci.org/Thor-x86/kuda) |
| 7 | + |
| 8 | + |
| 9 | +Fast and concurrent in-memory web server. It compress static files with [gzip](https://en.wikipedia.org/wiki/Gzip), put them into RAM, and serve them as a normal web server. So Dev/Ops don't have to worry about storage speed, just focus on networking matter. |
| 10 | + |
| 11 | +The best use case is serving Single Page Application (SPA) like [React](https://reactjs.org/), [Vue](https://vuejs.org/), and [Angular](https://angular.io/). |
| 12 | + |
| 13 | +Special thanks to [fasthttp](https://github.com/valyala/fasthttp) and contributors for making kuda possible 🤘 |
| 14 | + |
| 15 | +## How to use |
| 16 | + |
| 17 | +``` |
| 18 | +USAGE: |
| 19 | + kuda [arguments] <public_root_directory> |
| 20 | +
|
| 21 | +ARGUMENTS: |
| 22 | + --port=... : TCP Port to be listened (default: "8080") |
| 23 | + --origins=... : Which domains to be allowed by CORS policy (default: "") |
| 24 | + --port-tls=... : Use this to listen for HTTPS requests (default: "") |
| 25 | + --domain=... : Required to redirect from http to https (default: "localhost") |
| 26 | + --cert=... : SSL certificate file, required if "--port-tls" specified |
| 27 | + --key=... : SSL secret key file, required if "--port-tls" specified |
| 28 | +``` |
| 29 | + |
| 30 | +## Usage Example |
| 31 | + |
| 32 | +Let's say you're now in a directory with `kuda` executable and `my-app` as your react app project. |
| 33 | + |
| 34 | +``` |
| 35 | +cd my-app |
| 36 | +npm run build |
| 37 | +cd .. |
| 38 | +
|
| 39 | +./kuda my-app/build --port=8000 --origins=localhost:9000 |
| 40 | +``` |
| 41 | + |
| 42 | +After executed, it will put everything inside `my-app/build` into RAM and serve at port 8000. Beside of that, we're assuming the API backend runs on port 9000. Thus, we have to add it as allowed origins with `--origins=...` flag to prevent [CORS Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) problem. |
| 43 | + |
| 44 | +### How about SSL? |
| 45 | + |
| 46 | +Now we have same directory as above with `cert.pem` and `secret.key` inside of it. |
| 47 | + |
| 48 | +``` |
| 49 | +./kuda my-app/build --port=8000 --origins=localhost:9000 --port-tls=8090 --domain=localhost --cert=cert.pem --key=secret.key |
| 50 | +``` |
| 51 | + |
| 52 | +The `localhost:8000` is considered using HTTP protocol. So every connection coming to that port will be redirected to `https://localhost:8090`. |
| 53 | + |
| 54 | + |
| 55 | +### Serving Production App |
| 56 | + |
| 57 | +In production environment, assuming you have `www.my-domain.com`, it will be like: |
| 58 | + |
| 59 | +``` |
| 60 | +sudo ./kuda my-app/build --port=80 --origins=localhost:9000 --port-tls=443 --domain=www.my-domain.com --cert=/etc/ssl/certs/my-domain.pem --key=/etc/ssl/private/my-domain.key |
| 61 | +``` |
| 62 | + |
| 63 | +## With Docker |
| 64 | + |
| 65 | +Mostly, we deploy web app with docker and kubernetes (for orchestration). In order to do that, use this commands. |
| 66 | + |
| 67 | +``` |
| 68 | +docker pull kuda:latest |
| 69 | +docker run --name kuda-demo --volume my-compiled-webapp:/srv -p 8080:8080 --rm kuda:latest |
| 70 | +``` |
| 71 | + |
| 72 | +Where `my-compiled-webapp` is your directory with compiled app inside. **NEVER EVER** point project root directory as public directory, otherwise your machine will run out of memory very shortly! |
| 73 | + |
| 74 | +## With Docker Compose |
| 75 | + |
| 76 | +I would recommend you to use Docker Compose instead of plain Docker for sake of maintainability. This is an example of `docker-compose.yml`: |
| 77 | + |
| 78 | +```yml |
| 79 | +version: "3" |
| 80 | + |
| 81 | +services: |
| 82 | + kuda: |
| 83 | + image: kuda:latest |
| 84 | + volumes: |
| 85 | + - ./my-compiled-webapp:/srv |
| 86 | + environment: |
| 87 | + KUDA_PUBLIC_DIR: "/srv" |
| 88 | + KUDA_DOMAIN: "localhost" |
| 89 | + KUDA_PORT: "8080" |
| 90 | + KUDA_ORIGINS: "" |
| 91 | + KUDA_PORT_TLS: "" |
| 92 | + KUDA_CERT: "" |
| 93 | + KUDA_KEY: "" |
| 94 | + ports: |
| 95 | + - 8080:8080 |
| 96 | +``` |
| 97 | +
|
| 98 | +## Benchmark |
| 99 | +
|
| 100 | +I have no enough resource to benchmark Kuda Web Server myself. If you did benchmark and comparation with kuda, please let us know via **issue** section. |
| 101 | +
|
| 102 | +## Contribution |
| 103 | +
|
| 104 | +Anyone can contribute on this project. We welcome you to Pull Request or Open an Issue. To working on source code, you will require: |
| 105 | +- Linux or Mac preferred (Use [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) if you are Windows 10 user or [Cygwin](https://www.cygwin.com/) for older Windows) |
| 106 | +- Golang |
| 107 | +- Makefile |
| 108 | +- NPM (for demo) |
| 109 | +- Docker + Docker Compose (optional) |
| 110 | +
|
| 111 | +### Makefile Commands |
| 112 | +
|
| 113 | +There are things you can do with makefile on this project: |
| 114 | +- `make` -- Compile for all platforms and store them inside "build" directory |
| 115 | +- `make test` -- Run this everytime you want to pull request |
| 116 | +- `make clean` -- Removes all compiled files to reduce storage usage |
| 117 | +- `make demo` -- Run demonstration, go to `http://localhost:8080` on browser while running this command |
| 118 | + |
| 119 | +### Security Report |
| 120 | + |
| 121 | +To keep other users' security, please send email to [athaariqa@gmail.com](mailto://athaariqa@gmail.com) instead. **Do not** open issue for security report. |
0 commit comments