docs: improve docker docs for 5.x (#3476)

docker-examples/v4/plugins/docker-extend/Dockerfile

@@ -4,7 +4,7 @@ USER root
 
 ENV NODE_ENV=production
 
-RUN npm i && npm install verdaccio-aws-s3-storage
+RUN npm i && npm -g install verdaccio-aws-s3-storage
 
 USER verdaccio
 

docker-examples/v5/plugins/docker-build-install-plugin/Dockerfile

@@ -1,25 +1,7 @@
-# Docs based on https://github.com/xlts-dev/verdaccio-prometheus-middleware#installation
-
-# Docker multi-stage build - https://docs.docker.com/develop/develop-images/multistage-build/
-# Use an alpine node image to install the plugin
-FROM node:lts-alpine as builder
-
-# Install the metrics middleware plugin
-# npm docs
-# --global-style https://docs.npmjs.com/cli/v7/commands/npm-install#global-style
-# --no-bin-links https://docs.npmjs.com/cli/v7/commands/npm-install#bin-links
-# --omit=optional 
-RUN mkdir -p /verdaccio/plugins \
-  && cd /verdaccio/plugins \
-  && npm install --global-style --no-bin-links --omit=optional verdaccio-auth-memory@latest
-
 # The final built image will be based on the standard Verdaccio docker image.
 FROM verdaccio/verdaccio:5
-
-# Copy the plugin files over from the 'builder' node image.
-# The `$VERDACCIO_USER_UID` env variable is defined in the base `verdaccio/verdaccio` image.
-# Refer to: https://github.com/verdaccio/verdaccio/blob/v5.2.0/Dockerfile#L32
 ADD docker.yaml /verdaccio/conf/config.yaml  
-COPY --chown=$VERDACCIO_USER_UID:root --from=builder \
+USER root
-  /verdaccio/plugins/node_modules/verdaccio-auth-memory \
+RUN npm install --global verdaccio-static-token \
-  /verdaccio/plugins/verdaccio-auth-memory
+  && npm install --global verdaccio-auth-memory
+USER $VERDACCIO_USER_UID

docker-examples/v5/plugins/docker-build-install-plugin/README.md

@@ -38,9 +38,11 @@ FROM verdaccio/verdaccio:5
 
 # copy your modified config.yaml into the image
 ADD docker.yaml /verdaccio/conf/config.yaml
-
+# need it for install global plugins
-COPY --chown=$VERDACCIO_USER_UID:root --from=builder \
+USER root
-  /verdaccio/plugins/node_modules/verdaccio-auth-memory \
+# install plugins with npm global
-  /verdaccio/plugins/verdaccio-auth-memory
+RUN npm install --global verdaccio-static-token \
-
+  && npm install --global verdaccio-auth-memory
+# back to original user
+USER $VERDACCIO_USER_UID
 ```

docker-examples/v5/plugins/docker-build-install-plugin/docker.yaml

@@ -176,6 +176,13 @@ server:
 middlewares:
   audit:
     enabled: true
+  static-token:
+    - token: mySecureToken
+      user: systemUser
+      password: systemPassword
+    - token: ABCD1234
+      user: uncle
+      password: tom
 
 # https://verdaccio.org/docs/logger
 # log settings

docker-examples/v6/plugins/docker-build-install-plugin/docker.yaml

@@ -176,6 +176,13 @@ server:
 middlewares:
   audit:
     enabled: true
+  static-token:
+    - token: mySecureToken
+      user: systemUser
+      password: systemPassword
+    - token: ABCD1234
+      user: uncle
+      password: tom
 
 # https://verdaccio.org/docs/logger
 # log settings

website/versioned_docs/version-5.x/cli.md

@@ -31,15 +31,18 @@ Config files should be YAML, JSON or a NodeJS module. YAML format is detected by
 We use the **$XDG_DATA_HOME** environment by variable default to locate the storage by default which [should be the same](https://askubuntu.com/questions/538526/is-home-local-share-the-default-value-for-xdg-data-home-in-ubuntu-14-04) as $HOME/.local/share.
 If you are using a custom storage, this location is irrelevant.
 
+You can use `VERDACCIO_STORAGE_PATH` to define an alternative storage path,  read more about `VERDACCIO_STORAGE_PATH` [at the environment variables page](env.md#storage-path).
+
 ## Default database file location {#default-database-file-location}
 
 The default database file location is in the storage location.
 Starting with version 4.0.0, the database file name will be **.verdaccio-db.json** for a new installation of Verdaccio.
 When upgrading an existing Verdaccio server, the file name will remain **.sinopia-db.json**.
 
+> The database name `sinopia-db.json` is deprecated and support will be removed after v6.x
+
 
 ## Environment variables {#environment-variables}
 
-[Full list of environment variables](https://github.com/verdaccio/verdaccio/blob/master/docs/env.variables.md).
+[Full list of environment variables](env.md).
 
-* `VERDACCIO_HANDLE_KILL_SIGNALS` to enable gracefully shutdown (since v4.12.0)

website/versioned_docs/version-5.x/config.md

@@ -165,24 +165,11 @@ The new `VERDACCIO_PUBLIC_URL` is intended to be used behind proxies, this varia
 - Used as base path to serve UI resources as (js, favicon, etc)
 - Used on return metadata `dist` base path
 - Ignores `host` and `X-Forwarded-Proto` headers
-- If `url_prefix` is defined would be appened to the env variable.
+- If `url_prefix` is defined would be appended to the env variable.
 
-```
-VERDACCIO_PUBLIC_URL='https://somedomain.org';
-url_prefix: '/my_prefix'
 
-// url -> https://somedomain.org/my_prefix/
+Read more about `VERDACCIO_PUBLIC_URL` [at the environment variables page](env.md#public-url).
 
-VERDACCIO_PUBLIC_URL='https://somedomain.org';
-url_prefix: '/'
-
-// url -> https://somedomain.org/
-
-VERDACCIO_PUBLIC_URL='https://somedomain.org/first_prefix';
-url_prefix: '/second_prefix'
-
-// url -> https://somedomain.org/second_prefix/'
-```
 
 ### User Agent {#user-agent}
 

website/versioned_docs/version-5.x/docker.md

@@ -54,7 +54,11 @@ If you have [build an image locally](#build-your-own-docker-image) use `verdacci
 
 You can use `-v` to bind mount `conf`, `storage` and `plugins` to the hosts filesystem (example below).
 
-Note that if you do mount conf like this, that you will first need to supply a copy of config.yaml in that directory; the Docker container will not start properly if this file is missing. You can copy this file initially from https://github.com/verdaccio/verdaccio/blob/5.x/conf/docker.yaml. However, note the security warnings in that file; you will definitely want to lock it down in production.
+Note that if you do mount conf like this, that [you first need to supply a copy of config.yaml in that directory](https://github.com/verdaccio/verdaccio/tree/master/docker-examples/v5/plugins/docker-build-install-plugin). The Docker container will not start properly if this file is missing. 
+
+You can copy this file initially from https://github.com/verdaccio/verdaccio/blob/5.x/conf/docker.yaml. 
+
+However, note the security warnings in that file; you will definitely want to lock it down in production.
 
 ```bash
 V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio \
@@ -71,17 +75,9 @@ you need to make sure the mount directory is assigned to the right user. In abov
 you will get permission errors at runtime. 
 [Use docker volume](https://docs.docker.com/storage/volumes/) is recommended over using bind mount.
 
-Verdaccio 4 provides a new set of environment variables to modify either permissions, port or http protocol. Here the complete list:
+### Environment variables
-
-Property | default | Description
---- | --- | ---
-VERDACCIO_APPDIR | `/opt/verdaccio` | the docker working directory
-VERDACCIO_USER_NAME | `verdaccio` | the system user
-VERDACCIO_USER_UID | `10001` | the user id being used to apply folder permissions
-VERDACCIO_PORT | `4873` | the verdaccio port
-VERDACCIO_PROTOCOL | `http` | the default http protocol
-
 
+Verdaccio provides a new set of environment variables to modify either permissions, port or http protocol, see them at [the environment variables page](env.md#docker).
 
 ### SELinux {#selinux}
 
@@ -107,24 +103,62 @@ If you want to make the directory accessible only to a specific container, use `
 
 An alternative solution is to use [z and Z flags](https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label). To add the `z` flag to the mountpoint `./conf:/verdaccio/conf` simply change it to `./conf:/verdaccio/conf:z`. The `z` flag relabels the directory and makes it accessible by every container while the `Z` flags relables the directory and makes it accessible only to that specific container. However using these flags is dangerous. A small configuration mistake, like mounting `/home/user` or `/var` can mess up the labels on those directories and make the system unbootable.
 
-### Plugins {#plugins}
+## Plugins {#plugins}
 
 Plugins can be installed in a separate directory and mounted using Docker or Kubernetes, however make sure you build plugins with native dependencies using the same base image as the Verdaccio Dockerfile.
 
+### Creating your own `Dockerfile` using `verdaccio/verdaccio:tag` as base
+
+If the plugin already exist in some registry, it could be installed globally with `npm` command. 
+
 ```docker
+FROM verdaccio/verdaccio:5
+ADD docker.yaml /verdaccio/conf/config.yaml  
+USER root
+RUN npm install --global verdaccio-static-token \
+  && npm install --global verdaccio-auth-memory
+USER $VERDACCIO_USER_UID
+```
+
+For more detailed plugin example, check the with `docker-examples` [folder](https://github.com/verdaccio/verdaccio/tree/master/docker-examples/v5/plugins/docker-build-install-plugin).
+
+### Adding plugins with local plugins a `Dockerfile`
+
+If you don't have the packages available some registry and you want to try out a local plugin, you can use the folder `/verdaccio/plugins` for it, _verdaccio_ will look at this folder for plugins on startup.
+
+1. Create a base image with multi stage support.
+2. `ADD` the local plugin into the image
+3. Install dependencies, required if your plugin has dependencies, you might need to build in case you need a transpilation step (tsc, babel).
+4. Copying the final folder into the final image and applying permissions so verdaccio can find the folders (verdaccio uses custom user `$VERDACCIO_USER_UID`, read more [here](env.md#docker)).
+
+```
 FROM node:lts-alpine as builder
-RUN mkdir -p /verdaccio/plugins \
+RUN mkdir -p /verdaccio/plugins
-  && cd /verdaccio/plugins \
+ADD plugins/verdaccio-docker-memory /verdaccio/plugins/verdaccio-docker-memory
-  && npm install --global-style --no-bin-links --omit=optional verdaccio-auth-memory@latest
+RUN cd /verdaccio/plugins/verdaccio-docker-memory \
+  && npm install --production
 FROM verdaccio/verdaccio:5
 ADD docker.yaml /verdaccio/conf/config.yaml  
 COPY --chown=$VERDACCIO_USER_UID:root --from=builder \
-  /verdaccio/plugins/node_modules/verdaccio-auth-memory \
+  /verdaccio/plugins/verdaccio-docker-memory \
-  /verdaccio/plugins/verdaccio-auth-memory
+  /verdaccio/plugins/verdaccio-docker-memory
 ```
 
-For more information check real plugin examples with Docker in our [source code](https://github.com/verdaccio/verdaccio/tree/master/docker-examples/v5/plugins).
+For more detailed plugin example, check the with `docker-examples` [folder](https://github.com/verdaccio/verdaccio/tree/master/docker-examples/v5/plugins/docker-local-plugin).
 
+### Adding plugins without creating a new image
+
+1. Using `docker-compose.yaml` [example below](docker.md#using-docker-compose).
+2. Mapping volumes in docker, verdaccio will look up for plugins at `/verdaccio/plugins` by default.
+
+```
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio \
+  -p 4873:4873 \
+  -v $V_PATH/conf:/verdaccio/conf \
+  -v $V_PATH/storage:/verdaccio/storage \
+  -v $V_PATH/plugins:/verdaccio/plugins \
+  verdaccio/verdaccio
+```  
 
 ### Docker and custom port configuration {#docker-and-custom-port-configuration}
 
@@ -204,18 +238,19 @@ $ docker volume inspect verdaccio_verdaccio
 
 ## Build your own Docker image {#build-your-own-docker-image}
 
+Go to the [`5.x` branch](https://github.com/verdaccio/verdaccio/tree/5.x) and run:
 
 ```bash
 docker build -t verdaccio .
 ```
 
-There is also an npm script for building the docker image, so you can also do:
+There is also an yarn script for building the docker image, so you can also do:
 
 ```bash
 yarn run build:docker
 ```
 
-Note: The first build takes some minutes to build because it needs to run `npm install`,
+Note: The first build takes some minutes to build because it needs to run `yarn install`,
 and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
 
 Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.

website/versioned_docs/version-5.x/env.md

@@ -0,0 +1,70 @@
+---
+id: env
+title: Environment Variables
+---
+
+Verdaccio provides a set of environment variables to modify either permissions, port or http protocol. Here the complete list:
+
+### Docker {#docker}
+
+To change the behavior on runtime on running the image, these are the list of available variables.
+
+Variable | Default | Description
+--- | --- | ---
+VERDACCIO_APPDIR | `/opt/verdaccio` | the docker working directory
+VERDACCIO_USER_NAME | `verdaccio` | the system user
+VERDACCIO_USER_UID | `10001` | the user id being used to apply folder permissions
+VERDACCIO_PORT | `4873` | the verdaccio port
+VERDACCIO_PROTOCOL | `http` | the default http protocol
+
+
+### VERDACCIO_HANDLE_KILL_SIGNALS {#handle-kill-signals}
+
+Enables gracefully shutdown, more info at the [pull request #2121](https://github.com/verdaccio/verdaccio/pull/2121).
+
+> 
+
+### VERDACCIO_PUBLIC_URL {#public-url}
+
+Define a specific public url for your server, it overrules the `Host` and `X-Forwarded-Proto` header if a reverse proxy is being used, it takes in account the `url_prefix` if is defined.
+
+This is handy in such situations where a dynamic url is required.
+
+eg:
+
+```
+VERDACCIO_PUBLIC_URL='https://somedomain.org';
+url_prefix: '/my_prefix'
+
+// url -> https://somedomain.org/my_prefix/
+
+VERDACCIO_PUBLIC_URL='https://somedomain.org';
+url_prefix: '/'
+
+// url -> https://somedomain.org/
+
+VERDACCIO_PUBLIC_URL='https://somedomain.org/first_prefix';
+url_prefix: '/second_prefix'
+
+// url -> https://somedomain.org/second_prefix/'
+```
+
+### VERDACCIO_FORWARDED_PROTO {#handle-forwarded-proto}
+
+The default header to identify the protocol is `X-Forwarded-Proto`, but there are some environments which [uses something different](https://github.com/verdaccio/verdaccio/issues/990), to change it use the variable `VERDACCIO_FORWARDED_PROTO`
+
+```
+$ VERDACCIO_FORWARDED_PROTO=CloudFront-Forwarded-Proto verdaccio --listen 5000
+```
+
+### VERDACCIO_STORAGE_PATH {#storage-path}
+
+By default, the storage is taken from config file, but using this variable allows to set it from environment variable.
+
+### EXPERIMENTAL_VERDACCIO_LOGGER_COLORS {#logger-colors}
+
+Overrides `logs.colors` from the `config.yaml`.
+
+Note that any value that other than `false` will result in `true`.
+
+When both are not provided - the colors are on by default for TTY processes, and off for processes that are not.

website/versioned_sidebars/version-5.x-sidebars.json

@@ -17,9 +17,11 @@
             "setup-pnpm"
           ]
         },
+        "configuration",
         "who-is-using",
         "best",
         "docker",
+        "env",
         "protect-your-dependencies",
         "e2e",
         "verdaccio-programmatically",
@@ -41,7 +43,6 @@
       "type": "category",
       "label": "Features",
       "items": [
-        "configuration",
         "uplinks",
         "packages",
         "authentication",