From 9cd508e72005178bb92a06cd92f80527c88a8773 Mon Sep 17 00:00:00 2001 From: Juan Picado Date: Tue, 8 Nov 2022 19:52:40 +0100 Subject: [PATCH] docs: improve docker docs for 5.x (#3476) --- .../v4/plugins/docker-extend/Dockerfile | 2 +- .../docker-build-install-plugin/Dockerfile | 26 +------ .../docker-build-install-plugin/README.md | 12 +-- .../docker-build-install-plugin/docker.yaml | 7 ++ .../docker-build-install-plugin/docker.yaml | 7 ++ website/versioned_docs/version-5.x/cli.md | 7 +- website/versioned_docs/version-5.x/config.md | 17 +---- website/versioned_docs/version-5.x/docker.md | 75 ++++++++++++++----- website/versioned_docs/version-5.x/env.md | 70 +++++++++++++++++ .../version-5.x-sidebars.json | 3 +- 10 files changed, 160 insertions(+), 66 deletions(-) create mode 100644 website/versioned_docs/version-5.x/env.md diff --git a/docker-examples/v4/plugins/docker-extend/Dockerfile b/docker-examples/v4/plugins/docker-extend/Dockerfile index 022424c6c..537607ea6 100644 --- a/docker-examples/v4/plugins/docker-extend/Dockerfile +++ b/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 diff --git a/docker-examples/v5/plugins/docker-build-install-plugin/Dockerfile b/docker-examples/v5/plugins/docker-build-install-plugin/Dockerfile index 38c2eb238..edf47fe50 100644 --- a/docker-examples/v5/plugins/docker-build-install-plugin/Dockerfile +++ b/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 \ - /verdaccio/plugins/node_modules/verdaccio-auth-memory \ - /verdaccio/plugins/verdaccio-auth-memory +USER root +RUN npm install --global verdaccio-static-token \ + && npm install --global verdaccio-auth-memory +USER $VERDACCIO_USER_UID diff --git a/docker-examples/v5/plugins/docker-build-install-plugin/README.md b/docker-examples/v5/plugins/docker-build-install-plugin/README.md index 2f440cff4..f93ea07ab 100644 --- a/docker-examples/v5/plugins/docker-build-install-plugin/README.md +++ b/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 - -COPY --chown=$VERDACCIO_USER_UID:root --from=builder \ - /verdaccio/plugins/node_modules/verdaccio-auth-memory \ - /verdaccio/plugins/verdaccio-auth-memory - +# need it for install global plugins +USER root +# install plugins with npm global +RUN npm install --global verdaccio-static-token \ + && npm install --global verdaccio-auth-memory +# back to original user +USER $VERDACCIO_USER_UID ``` diff --git a/docker-examples/v5/plugins/docker-build-install-plugin/docker.yaml b/docker-examples/v5/plugins/docker-build-install-plugin/docker.yaml index 3bc70a146..e17bbc76c 100644 --- a/docker-examples/v5/plugins/docker-build-install-plugin/docker.yaml +++ b/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 diff --git a/docker-examples/v6/plugins/docker-build-install-plugin/docker.yaml b/docker-examples/v6/plugins/docker-build-install-plugin/docker.yaml index 3bc70a146..e17bbc76c 100644 --- a/docker-examples/v6/plugins/docker-build-install-plugin/docker.yaml +++ b/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 diff --git a/website/versioned_docs/version-5.x/cli.md b/website/versioned_docs/version-5.x/cli.md index 4cd1e6fad..0c0ca01c4 100644 --- a/website/versioned_docs/version-5.x/cli.md +++ b/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) diff --git a/website/versioned_docs/version-5.x/config.md b/website/versioned_docs/version-5.x/config.md index bd33bda2f..5ce09b7b9 100644 --- a/website/versioned_docs/version-5.x/config.md +++ b/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} diff --git a/website/versioned_docs/version-5.x/docker.md b/website/versioned_docs/version-5.x/docker.md index 6ab54b61b..45dbf8eb1 100644 --- a/website/versioned_docs/version-5.x/docker.md +++ b/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: - -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 - +### Environment variables +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 \ - && cd /verdaccio/plugins \ - && npm install --global-style --no-bin-links --omit=optional verdaccio-auth-memory@latest +RUN mkdir -p /verdaccio/plugins +ADD plugins/verdaccio-docker-memory /verdaccio/plugins/verdaccio-docker-memory +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-auth-memory + /verdaccio/plugins/verdaccio-docker-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`. diff --git a/website/versioned_docs/version-5.x/env.md b/website/versioned_docs/version-5.x/env.md new file mode 100644 index 000000000..2d6cd407f --- /dev/null +++ b/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. diff --git a/website/versioned_sidebars/version-5.x-sidebars.json b/website/versioned_sidebars/version-5.x-sidebars.json index 56d3a0f4d..f3cc27bca 100644 --- a/website/versioned_sidebars/version-5.x-sidebars.json +++ b/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",