diff --git a/logo.png b/logo.png new file mode 100644 index 0000000..e9da809 Binary files /dev/null and b/logo.png differ diff --git a/readme.md b/readme.md index 87b17bc..5f9a013 100644 --- a/readme.md +++ b/readme.md @@ -1,53 +1,94 @@ -# npm-cache-proxy +

+ -![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/emeralt/npm-cache-proxy.svg?style=for-the-badge) +npm-cache-proxy +

-- [npm-cache-proxy](#npm-cache-proxy) - - [Quick start](#quick-start) - - [Deployment](#deployment) - - [Usage](#usage) - - [`ncp`](#ncp) - - [`ncp list`](#ncp-list) - - [`ncp purge`](#ncp-purge) - - [Programmatic usage](#programmatic-usage) - - [Example](#example) - - [Benchmark](#benchmark) - - [License](#license) +

+ + Current Release + + + CI Build + + + Licence + +

-## 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. +> `npm-cache-proxy` is a lightweight npm caching proxy written in Go that achives warp speeds by using Redis for data storage. B-b-blazing fast! + +
+Table of Contents +

+ +- [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) + +

+
+ +## Getting started +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 fastest way to get started with NCP is to use Docker image: ```bash -docker run -e REDIS_ADDRESS=host.docker.internal:6379 -p 8080:8080 -it emeralt/npm-cache-proxy +# run proxy inside of docker container in background +docker run -e REDIS_ADDRESS=host.docker.internal:6379 -p 8080:8080 -it emeralt/npm-cache-proxy -d + +# configure npm to use caching proxy as registry +npm config set registry http://localhost:8080 ``` -## Deployment -NCP can be deployed using Kubernetes, Docker Compose or any other container orchestration platform. NCP supports running indefinite amount of instances simultaneously. +## CLI +Additionally, NCP provides a command line utility for proxy configuration and data management. -## Usage +--- + +| Global Options | Env | Default | Description | +| ----------------------------- | ---------------- | ----------------------- | ----------------- | +| `--redis-address
` | `REDIS_ADDRESS` | `http://localhost:6379` | Redis address | +| `--redis-database ` | `REDIS_DATABASE` | `0` | Redis database | +| `--redis-password ` | `REDIS_PASSWORD` | - | Redis password | +| `--redis-prefix ` | `REDIS_PREFIX` | `ncp-` | Redis keys prefix | + +--- ### `ncp` Start proxy server. -| Options | Env | Default | Description | -| ----------------------------- | ------------------ | ---------------------------- | ----------------------------------- | -| `--listen
` | `LISTEN_ADDRESS` | `locahost:8080` | Address to listen | -| `--upstream
` | `UPSTREAM_ADDRESS` | `https://registry.npmjs.org` | Upstream registry address | -| `--cache-limit ` | `CACHE_LIMIT` | - | Cached packages count limit | -| `--cache-ttl ` | `CACHE_TTL` | `3600` | Cache expiration timeout in seconds | -| `--redis-address
` | `REDIS_ADDRESS` | `http://localhost:6379` | Redis address | -| `--redis-database ` | `REDIS_DATABASE` | `0` | Redis database | -| `--redis-password ` | `REDIS_PASSWORD` | - | Redis password | -| `--redis-prefix ` | `REDIS_PREFIX` | `ncp-` | Redis keys prefix | +```bash +ncp --listen "localhost:1234" # listen on port 1234 +``` + +| Options | Env | Default | Description | +| ----------------------- | ------------------ | ---------------------------- | ----------------------------------- | +| `--listen
` | `LISTEN_ADDRESS` | `locahost:8080` | Address to listen | +| `--upstream
` | `UPSTREAM_ADDRESS` | `https://registry.npmjs.org` | Upstream registry address | +| `--cache-limit ` | `CACHE_LIMIT` | - | Cached packages count limit | +| `--cache-ttl ` | `CACHE_TTL` | `3600` | Cache expiration timeout in seconds | + +--- ### `ncp list` +List all cached packages. -List cached packages. +--- ### `ncp purge` +Purge all cached packages. -Purge 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). @@ -70,12 +111,18 @@ import ( func main() { proxy := npmproxy.Proxy{ + // you can provide you own Database + // or use an existing one Database: npmproxy.DatabaseRedis{ Client: redis.NewClient(&redis.Options{ Addr: "localhost:6379", }), }, + + // allows to reuse tcp connections HttpClient: &http.Client{}, + + // allows to get options dynamically GetOptions: func() (npmproxy.Options, error) { return npmproxy.Options{ DatabasePrefix: "ncp-", @@ -85,16 +132,21 @@ func main() { }, } + // listen on http://localhost:8080 proxy.Server(npmproxy.ServerOptions{ ListenAddress: "localhost:8080", }).ListenAndServe() } ``` +## Deployment +NCP can be deployed using Kubernetes, Docker Compose or any other container orchestration platform. NCP supports running indefinite amount of instances simultaneously. + ## Benchmark +Macbook Pro 15″ 2017, Intel Core i7-7700HQ. Note `GOMACPROCS=1`. ```bash -# GOMAXPROCS=1 GIN_MODE=release ncp --listen localhost:8080 +# GOMAXPROCS=1 ncp --listen localhost:8080 $ go-wrk -c 100 -d 5 http://localhost:8080/ascii Running 5s test @ http://localhost:8080/ascii