docs: rewrite readme
This commit is contained in:
Ilya Atamas
parent
7c8b90ff6b
commit
dbd9c683f9
173
readme.md
173
readme.md
@ -1,10 +1,8 @@
|
|||||||
<h1 align="center">
|
<div align="center">
|
||||||
<img width="400" src="./logo.png">
|
<img width="450" src="./logo.png">
|
||||||
|
|
||||||
npm-cache-proxy
|
<h1>npm-cache-proxy</h1>
|
||||||
</h1>
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<a href="https://hub.docker.com/r/emeralt/npm-cache-proxy/tags">
|
<a href="https://hub.docker.com/r/emeralt/npm-cache-proxy/tags">
|
||||||
<img src="https://img.shields.io/github/release/emeralt/npm-cache-proxy.svg" alt="Current Release" />
|
<img src="https://img.shields.io/github/release/emeralt/npm-cache-proxy.svg" alt="Current Release" />
|
||||||
</a>
|
</a>
|
||||||
@ -14,33 +12,32 @@ npm-cache-proxy
|
|||||||
<a href="https://github.com/emeralt/npm-cache-proxy/blob/master/liscense">
|
<a href="https://github.com/emeralt/npm-cache-proxy/blob/master/liscense">
|
||||||
<img src="https://img.shields.io/github/license/emeralt/npm-cache-proxy.svg" alt="Licence">
|
<img src="https://img.shields.io/github/license/emeralt/npm-cache-proxy.svg" alt="Licence">
|
||||||
</a>
|
</a>
|
||||||
</p>
|
</div>
|
||||||
|
|
||||||
> `npm-cache-proxy` is a lightweight npm caching proxy written in Go that achieves warp speeds by using Redis for data storage. B-b-blazing fast!
|
<br />
|
||||||
|
<br />
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
#### ⚡️ Performance
|
||||||
|
NCP is a tiny but very fast caching proxy written and Go. It uses Redis for data storage, which in combination with the speed of Go makes it incredibly fast. NCP is well-optimized and can be run on almost any platform, so if you have a Raspberry Pi, you can install NCP as your local cache there.
|
||||||
|
|
||||||
|
#### ✨ Modularity
|
||||||
|
NCP is modular. Now it has only one database adapter which is Redis. If you need support for any other database, feel free to open an issue or implement it [on your own](https://github.com/emeralt/npm-cache-proxy/blob/7c8b90ff6ba0656f60e3de915b9fb4eaabfb467b/proxy/proxy.go#L29) and then open a pull request (_bonus points_).
|
||||||
|
|
||||||
|
#### 💡 Simplicity
|
||||||
|
NCP is very simple. It just proxies requests to an upstream registry, caches response and returns cached response for next requests to the same package. Cached data are stored in Redis with an original request URL as a key.
|
||||||
|
|
||||||
|
|
||||||
<details>
|
<br />
|
||||||
<summary>Table of Contents</summary>
|
|
||||||
<p>
|
|
||||||
|
|
||||||
- [Getting started](#getting-started)
|
|
||||||
- [CLI](#cli)
|
|
||||||
- [`ncp`](#ncp)
|
|
||||||
- [`ncp list`](#ncp-list)
|
|
||||||
- [`ncp purge`](#ncp-purge)
|
|
||||||
- [Programmatic usage](#programmatic-usage)
|
|
||||||
- [Example](#example)
|
|
||||||
- [Deployment](#deployment)
|
|
||||||
- [Benchmark](#benchmark)
|
|
||||||
- [License](#license)
|
|
||||||
|
|
||||||
</p>
|
## Installation
|
||||||
</details>
|
NCP binaries for different paltforms can be downloaded can be downloaded on the [Releases](https://github.com/emeralt/npm-cache-proxy/releases) page. Also, Docker image is provided on [Docker Hub](https://cloud.docker.com/u/emeralt/repository/docker/emeralt/npm-cache-proxy).
|
||||||
|
|
||||||
## Getting started
|
#### 💫 Quick Start
|
||||||
Release binaries for different platforms can be downloaded on the [Releases](https://github.com/emeralt/npm-cache-proxy/releases) page. Also, [Docker image](https://cloud.docker.com/u/emeralt/repository/docker/emeralt/npm-cache-proxy) is provided.
|
The quickies way to get started with NCP is to use Docker.
|
||||||
|
|
||||||
The fastest way to get started with NCP is to use Docker image:
|
|
||||||
```bash
|
```bash
|
||||||
# run proxy inside of docker container in background
|
# run proxy inside of docker container in background
|
||||||
docker run -e REDIS_ADDRESS=host.docker.internal:6379 -p 8080:8080 -it -d emeralt/npm-cache-proxy
|
docker run -e REDIS_ADDRESS=host.docker.internal:6379 -p 8080:8080 -it -d emeralt/npm-cache-proxy
|
||||||
@ -49,56 +46,90 @@ docker run -e REDIS_ADDRESS=host.docker.internal:6379 -p 8080:8080 -it -d emeral
|
|||||||
npm config set registry http://localhost:8080
|
npm config set registry http://localhost:8080
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<br />
|
||||||
|
|
||||||
## CLI
|
## CLI
|
||||||
Additionally, NCP provides a command line utility for proxy configuration and data management.
|
NCP provides command line interface for interaction with a cached data.
|
||||||
|
|
||||||
---
|
#### `ncp`
|
||||||
|
Start NCP server.
|
||||||
|
|
||||||
| Global Options | Env | Default | Description |
|
<details>
|
||||||
| ----------------------------- | ---------------- | ----------------------- | ----------------- |
|
<summary>Options</summary>
|
||||||
| `--redis-address <address>` | `REDIS_ADDRESS` | `http://localhost:6379` | Redis address |
|
|
||||||
| `--redis-database <database>` | `REDIS_DATABASE` | `0` | Redis database |
|
|
||||||
| `--redis-password <password>` | `REDIS_PASSWORD` | - | Redis password |
|
|
||||||
| `--redis-prefix <prefix>` | `REDIS_PREFIX` | `ncp-` | Redis keys prefix |
|
|
||||||
|
|
||||||
---
|
| Options | Env | Default | Description |
|
||||||
|
| ----------------------------- | ------------------ | ---------------------------- | ----------------------------------- |
|
||||||
|
| `--listen <address>` | `LISTEN_ADDRESS` | `locahost:8080` | Address to listen |
|
||||||
|
| `--upstream <address>` | `UPSTREAM_ADDRESS` | `https://registry.npmjs.org` | Upstream registry address |
|
||||||
|
| `--silent <address>` | `SILENT` | `0` | Disable logs |
|
||||||
|
| `--cache-limit <count>` | `CACHE_LIMIT` | - | Cached packages count limit |
|
||||||
|
| `--cache-ttl <timeout>` | `CACHE_TTL` | `3600` | Cache expiration timeout in seconds |
|
||||||
|
| `--redis-address <address>` | `REDIS_ADDRESS` | `http://localhost:6379` | Redis address |
|
||||||
|
| `--redis-database <database>` | `REDIS_DATABASE` | `0` | Redis database |
|
||||||
|
| `--redis-password <password>` | `REDIS_PASSWORD` | - | Redis password |
|
||||||
|
| `--redis-prefix <prefix>` | `REDIS_PREFIX` | `ncp-` | Redis keys prefix |
|
||||||
|
|
||||||
### `ncp`
|
</details>
|
||||||
|
|
||||||
Start proxy server.
|
#### `ncp list`
|
||||||
|
List cached url paths.
|
||||||
|
|
||||||
|
#### `ncp purge`
|
||||||
|
Purge cached url paths.
|
||||||
|
|
||||||
|
|
||||||
|
<br />
|
||||||
|
|
||||||
|
|
||||||
|
## Benchmark
|
||||||
|
Benchmark is run on Macbook Pro 15″ 2017, Intel Core i7-7700HQ.
|
||||||
|
|
||||||
|
#### 1️⃣ 1 process
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ncp --listen "localhost:1234" # listen on port 1234
|
# GOMAXPROCS=1 ncp --silent
|
||||||
|
|
||||||
|
$ go-wrk -c 100 -d 6 http://localhost:8080/tiny-tarball
|
||||||
|
Running 6s test @ http://localhost:8080/tiny-tarball
|
||||||
|
100 goroutine(s) running concurrently
|
||||||
|
|
||||||
|
70755 requests in 5.998378587s, 91.16MB read
|
||||||
|
|
||||||
|
Requests/sec: 11795.69
|
||||||
|
Transfer/sec: 15.20MB
|
||||||
|
Avg Req Time: 8.477674ms
|
||||||
|
Fastest Request: 947.743µs
|
||||||
|
Slowest Request: 815.787409ms
|
||||||
|
Number of Errors: 0
|
||||||
```
|
```
|
||||||
|
|
||||||
| Options | Env | Default | Description |
|
#### ♾ unlimited processes
|
||||||
| ----------------------- | ------------------ | ---------------------------- | ----------------------------------- |
|
|
||||||
| `--listen <address>` | `LISTEN_ADDRESS` | `locahost:8080` | Address to listen |
|
|
||||||
| `--upstream <address>` | `UPSTREAM_ADDRESS` | `https://registry.npmjs.org` | Upstream registry address |
|
|
||||||
| `--cache-limit <count>` | `CACHE_LIMIT` | - | Cached packages count limit |
|
|
||||||
| `--cache-ttl <timeout>` | `CACHE_TTL` | `3600` | Cache expiration timeout in seconds |
|
|
||||||
| `--silent <address>` | `SILENT` | `0` | Disable logs |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `ncp list`
|
|
||||||
List all cached packages.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### `ncp purge`
|
|
||||||
Purge all cached packages.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Programmatic usage
|
|
||||||
Along with the CLI, go package is provided. Documentation is available on [godoc.org](https://godoc.org/github.com/emeralt/npm-cache-proxy/proxy).
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go get -u github.com/emeralt/npm-cache-proxy/proxy
|
# ncp --silent
|
||||||
|
|
||||||
|
$ go-wrk -c 100 -d 6 http://localhost:8080/tiny-tarball
|
||||||
|
Running 6s test @ http://localhost:8080/tiny-tarball
|
||||||
|
100 goroutine(s) running concurrently
|
||||||
|
|
||||||
|
115674 requests in 5.98485984s, 149.04MB read
|
||||||
|
|
||||||
|
Requests/sec: 19327.77
|
||||||
|
Transfer/sec: 24.90MB
|
||||||
|
Avg Req Time: 5.173902ms
|
||||||
|
Fastest Request: 273.015µs
|
||||||
|
Slowest Request: 34.777963ms
|
||||||
|
Number of Errors: 0
|
||||||
```
|
```
|
||||||
|
|
||||||
### Example
|
|
||||||
|
<br />
|
||||||
|
|
||||||
|
|
||||||
|
## Programmatic Usage
|
||||||
|
NCP provides `proxy` go package that can be used programmatically. Docs are available on [godoc.org](https://godoc.org/github.com/emeralt/npm-cache-proxy/proxy).
|
||||||
|
|
||||||
|
#### 🤖 Example
|
||||||
```golang
|
```golang
|
||||||
package main
|
package main
|
||||||
|
|
||||||
@ -141,27 +172,9 @@ func main() {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Deployment
|
|
||||||
NCP can be deployed using Kubernetes, Docker Compose or any other container orchestration platform. NCP supports running indefinite amount of instances simultaneously.
|
|
||||||
|
|
||||||
## Benchmark
|
<br />
|
||||||
Macbook Pro 15″ 2017, Intel Core i7-7700HQ. Note `GOMAXPROCS=1`.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# SILENT=1 GIN_MODE=release GOMAXPROCS=1 ncp
|
|
||||||
|
|
||||||
$ go-wrk -c 100 -d 10 http://localhost:8080/ascii
|
|
||||||
Running 10s test @ http://localhost:8080/ascii
|
|
||||||
100 goroutine(s) running concurrently
|
|
||||||
120227 requests in 9.996788553s, 136.21MB read
|
|
||||||
Requests/sec: 12026.56
|
|
||||||
Transfer/sec: 13.63MB
|
|
||||||
Avg Req Time: 8.314928ms
|
|
||||||
Fastest Request: 1.157793ms
|
|
||||||
Slowest Request: 782.917402ms
|
|
||||||
Number of Errors: 0
|
|
||||||
```
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[MIT](./license)
|
[MIT](./license)
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user