From 236f98bad87341be7ea3b59724bdf92f5c8589f1 Mon Sep 17 00:00:00 2001 From: 030 Date: Fri, 23 Sep 2022 23:12:51 +0200 Subject: [PATCH] docs: [#21] Describe how to configure and start YAAM. --- README.md | 56 ++++++++++++----- deployments/k8s-openshift/deploy.yml | 2 +- docs/CHANGELOG.md | 12 +++- docs/config/BASE.md | 6 ++ docs/config/GENERIC.md | 11 ++++ docs/{usage/CONFIG.md => config/MAVEN.md} | 67 +++++++++++++++------ docs/config/NPM.md | 17 ++++++ docs/{usage/GRADLE.md => preserve/MAVEN.md} | 6 +- docs/preserve/NPM.md | 17 ++++++ docs/{usage => publish}/GENERIC.md | 10 --- docs/publish/MAVEN.md | 7 +++ docs/start/BINARY.md | 7 +++ docs/{usage => start}/DOCKER.md | 3 +- docs/{usage => start}/K8SOPENSHIFT.md | 0 docs/unify/MAVEN.md | 21 +++++++ docs/usage/BINARY.md | 7 --- docs/usage/PUBLISH.md | 5 -- 17 files changed, 195 insertions(+), 59 deletions(-) create mode 100644 docs/config/BASE.md create mode 100644 docs/config/GENERIC.md rename docs/{usage/CONFIG.md => config/MAVEN.md} (56%) create mode 100644 docs/config/NPM.md rename docs/{usage/GRADLE.md => preserve/MAVEN.md} (50%) create mode 100644 docs/preserve/NPM.md rename docs/{usage => publish}/GENERIC.md (84%) create mode 100644 docs/publish/MAVEN.md create mode 100644 docs/start/BINARY.md rename docs/{usage => start}/DOCKER.md (86%) rename docs/{usage => start}/K8SOPENSHIFT.md (100%) create mode 100644 docs/unify/MAVEN.md delete mode 100644 docs/usage/BINARY.md delete mode 100644 docs/usage/PUBLISH.md diff --git a/README.md b/README.md index b7bfa7e..0949e16 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # YAAM [![CI](https://github.com/030/yaam/workflows/Go/badge.svg?event=push)](https://github.com/030/yaam/actions?query=workflow%3AGo) -[![GoDoc Widget]][GoDoc] +[![GoDoc Widget]][godoc] ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/030/yaam) [![Go Report Card](https://goreportcard.com/badge/github.com/030/yaam)](https://goreportcard.com/report/github.com/030/yaam) [![StackOverflow SE Questions](https://img.shields.io/stackexchange/stackoverflow/t/yaam.svg?logo=stackoverflow)](https://stackoverflow.com/tags/yaam) @@ -39,29 +39,57 @@ [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) -[GoDoc]: https://godoc.org/github.com/030/yaam -[GoDoc Widget]: https://godoc.org/github.com/030/yaam?status.svg +[godoc]: https://godoc.org/github.com/030/yaam +[godoc widget]: https://godoc.org/github.com/030/yaam?status.svg Although there are many artifact managers, like Artifactory, Nexus3 and Verdaccio, they are either monoliths, consume a lot of resources (memory and CPU), lack Infrastructure as Code (IaC) or do not support all kind of artifact types. Yet Another Artifact Manager (YAAM): -* is an artifact manager like Artifactory, Nexus3 or Verdaccio. -* enforces IaC. -* has no UI. -* does not have a database. -* scales horizontally. -* supports downloading and publication of Generic, Maven and NPM artefacts, +- is an artifact manager like Artifactory, Nexus3 or Verdaccio. +- enforces IaC. +- has no UI. +- does not have a database. +- scales horizontally. +- supports downloading and publication of Generic, Maven and NPM artefacts, preserves NPM and Maven packages from public repositories and unifies Maven repositories. -## Usage +## Configuration -* [Binary.](docs/usage/BINARY.md) -* [Docker.](docs/usage/DOCKER.md) -* [K8s/OpenShift.](docs/usage/K8SOPENSHIFT.md) +### General + +- [Base.](docs/config/BASE.md) + +### Artifact types + +- [Generic.](docs/config/GENERIC.md) +- [Maven.](docs/config/MAVEN.md) +- [NPM.](docs/config/NPM.md) + +## Start + +- [Binary.](docs/start/BINARY.md) +- [Docker.](docs/start/DOCKER.md) +- [K8s/OpenShift.](docs/start/K8SOPENSHIFT.md) + +## Capabilities + +### Publish + +- [Generic.](docs/publish/GENERIC.md) +- [Maven.](docs/publish/MAVEN.md) + +### Preserve + +- [Maven.](docs/preserve/MAVEN.md) +- [NPM.](docs/preserve/NPM.md) + +### Unify + +- [Maven.](docs/unify/MAVEN.md) ## Other -* [Background.](docs/other/BACKGROUND.md) +- [Background.](docs/other/BACKGROUND.md) diff --git a/deployments/k8s-openshift/deploy.yml b/deployments/k8s-openshift/deploy.yml index 9f0a197..be88d29 100644 --- a/deployments/k8s-openshift/deploy.yml +++ b/deployments/k8s-openshift/deploy.yml @@ -138,7 +138,7 @@ spec: secretKeyRef: name: creds key: pass - image: utrecht/yaam:v0.4.0 + image: utrecht/yaam:v0.4.1 livenessProbe: httpGet: path: /status diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 8c785fc..c8a80ce 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,6 +2,15 @@ ## [Unreleased] + +## [v0.4.1] - 2022-09-23 +### Docs +- [[#21](https://github.com/030/yaam/issues/21)] Describe how to configure and start YAAM. + +### Fix +- Updated outdated CHANGELOG. + + ## [v0.4.0] - 2022-09-21 ### Docs @@ -28,7 +37,8 @@ ## v0.2.1 - 2022-08-23 -[Unreleased]: https://github.com/030/yaam/compare/v0.4.0...HEAD +[Unreleased]: https://github.com/030/yaam/compare/v0.4.1...HEAD +[v0.4.1]: https://github.com/030/yaam/compare/v0.4.0...v0.4.1 [v0.4.0]: https://github.com/030/yaam/compare/v0.3.0...v0.4.0 [v0.3.0]: https://github.com/030/yaam/compare/v0.2.0...v0.3.0 [v0.2.0]: https://github.com/030/yaam/compare/v0.1.0...v0.2.0 diff --git a/docs/config/BASE.md b/docs/config/BASE.md new file mode 100644 index 0000000..c87c8c2 --- /dev/null +++ b/docs/config/BASE.md @@ -0,0 +1,6 @@ +# Config + +```bash +mkdir -p ~/.yaam/conf +chown 9999 -R ~/.yaam/ +``` diff --git a/docs/config/GENERIC.md b/docs/config/GENERIC.md new file mode 100644 index 0000000..d152b8c --- /dev/null +++ b/docs/config/GENERIC.md @@ -0,0 +1,11 @@ +# generic + +## Configuration + +~/.yaam/conf/repositories/generic.yaml + +```bash +--- +allowedRepos: + - something +``` diff --git a/docs/usage/CONFIG.md b/docs/config/MAVEN.md similarity index 56% rename from docs/usage/CONFIG.md rename to docs/config/MAVEN.md index 5d38a78..f3a90b1 100644 --- a/docs/usage/CONFIG.md +++ b/docs/config/MAVEN.md @@ -1,39 +1,39 @@ -# Config +# Maven -```bash -mkdir -p ~/.yaam/conf -chown 9999 -R ~/.yaam/ -``` - -vim ~/.yaam/conf/caches.yaml +~/.yaam/conf/caches.yaml ```bash +--- mavenReposAndUrls: 3rdparty-maven: https://repo.maven.apache.org/maven2/ 3rdparty-maven-gradle-plugins: https://plugins.gradle.org/m2/ 3rdparty-maven-spring: https://repo.spring.io/release/ ``` -vim ~/.yaam/conf/groups.yaml +~/.yaam/conf/repositories/maven.yaml ```bash -groups: - hello: - - releases - - 3rdparty-maven - - 3rdparty-maven-gradle-plugins - - 3rdparty-maven-spring +--- +allowedRepos: + - releases ``` -vim ~/.yaam/conf/repositories.yaml +~/.yaam/conf/groups.yaml ```bash -maven: - - releases +--- +groups: + hello: + - maven/releases + - maven/3rdparty-maven + - maven/3rdparty-maven-gradle-plugins + - maven/3rdparty-maven-spring ``` ## Gradle +### Preserve + Adjust the `build.gradle` and/or `settings.gradle`: ```bash @@ -73,3 +73,36 @@ repositories { } } ``` + +### publish + +```bash +publishing { + publications { + mavenJava(MavenPublication) { + versionMapping { + usage('java-api') { + fromResolutionOf('runtimeClasspath') + } + usage('java-runtime') { + fromResolutionResult() + } + } + } + } + + repositories { + maven { + allowInsecureProtocol true + url 'http://localhost:25213/maven/releases/' + authentication { + basic(BasicAuthentication) + } + credentials { + username "hello" + password "world" + } + } + } +} +``` diff --git a/docs/config/NPM.md b/docs/config/NPM.md new file mode 100644 index 0000000..944280a --- /dev/null +++ b/docs/config/NPM.md @@ -0,0 +1,17 @@ +# NPM + +~/.yaam/conf/caches.yaml + +```bash +--- +mavenReposAndUrls: + 3rdparty-npm: https://registry.npmjs.org/ +``` + +~/.yaam/conf/repositories/npm.yaml + +```bash +--- +allowedRepos: + - npm-releases +``` diff --git a/docs/usage/GRADLE.md b/docs/preserve/MAVEN.md similarity index 50% rename from docs/usage/GRADLE.md rename to docs/preserve/MAVEN.md index a433e55..3a2105c 100644 --- a/docs/usage/GRADLE.md +++ b/docs/preserve/MAVEN.md @@ -1,7 +1,7 @@ -# Gradle +# Maven -## Cache artifacts +## Gradle ```bash ./gradlew clean build -``` \ No newline at end of file +``` diff --git a/docs/preserve/NPM.md b/docs/preserve/NPM.md new file mode 100644 index 0000000..564afe9 --- /dev/null +++ b/docs/preserve/NPM.md @@ -0,0 +1,17 @@ +# NPM + +Create a `.npmrc` file in the directory of a particular NPM project: + +```bash +registry=http://localhost:25213/npm/3rdparty-npm/ +always-auth=true +_auth=aGVsbG86d29ybGQ= +cache=/tmp/some-yaam-repo/npm/cache20220914120431999 +``` + +Note: the `_auth` key should be populated with the output of: +`echo -n 'someuser:somepass' | openssl base64`. + +```bash +npm i +``` diff --git a/docs/usage/GENERIC.md b/docs/publish/GENERIC.md similarity index 84% rename from docs/usage/GENERIC.md rename to docs/publish/GENERIC.md index c57d57c..92cdd63 100644 --- a/docs/usage/GENERIC.md +++ b/docs/publish/GENERIC.md @@ -1,15 +1,5 @@ # generic -## Configuration - -~/.yaam/conf/repositories/generic.yaml - -```bash ---- -allowedRepos: - - something -``` - ## Upload ```bash diff --git a/docs/publish/MAVEN.md b/docs/publish/MAVEN.md new file mode 100644 index 0000000..7040963 --- /dev/null +++ b/docs/publish/MAVEN.md @@ -0,0 +1,7 @@ +# Maven + +## Gradle + +```bash +./gradle publish +``` diff --git a/docs/start/BINARY.md b/docs/start/BINARY.md new file mode 100644 index 0000000..0ffd9c4 --- /dev/null +++ b/docs/start/BINARY.md @@ -0,0 +1,7 @@ +# Binary + +## Start + +```bash +YAAM_DEBUG=true YAAM_HOME=/tmp/some-yaam-repo YAAM_USER=hello YAAM_PASS=world ./yaam +``` diff --git a/docs/usage/DOCKER.md b/docs/start/DOCKER.md similarity index 86% rename from docs/usage/DOCKER.md rename to docs/start/DOCKER.md index 599c755..f6fd197 100644 --- a/docs/usage/DOCKER.md +++ b/docs/start/DOCKER.md @@ -6,8 +6,9 @@ docker run \ -v /home/${USER}/.yaam/conf:/opt/yaam/.yaam/conf \ -v /home/${USER}/.yaam/repositories:/opt/yaam/.yaam/repositories \ + -e YAAM_DEBUG=true \ -e YAAM_USER=hello \ -e YAAM_PASS=world \ -p 25213:25213 \ - -it utrecht/yaam:v0.4.0 + -it utrecht/yaam:v0.4.1 ``` diff --git a/docs/usage/K8SOPENSHIFT.md b/docs/start/K8SOPENSHIFT.md similarity index 100% rename from docs/usage/K8SOPENSHIFT.md rename to docs/start/K8SOPENSHIFT.md diff --git a/docs/unify/MAVEN.md b/docs/unify/MAVEN.md new file mode 100644 index 0000000..48e2751 --- /dev/null +++ b/docs/unify/MAVEN.md @@ -0,0 +1,21 @@ +# Maven + +## Gradle + +Adjust the repositories sections in the build.gradle and settings.gradle: + +```bash +repositories { + maven { + allowInsecureProtocol true + url 'http://localhost:25213/maven/groups/hello/' + authentication { + basic(BasicAuthentication) + } + credentials { + username "hello" + password "world" + } + } +} +``` diff --git a/docs/usage/BINARY.md b/docs/usage/BINARY.md deleted file mode 100644 index a9dbaee..0000000 --- a/docs/usage/BINARY.md +++ /dev/null @@ -1,7 +0,0 @@ -# Binary - -## Start - -```bash -YAAM_DEBUG=true YAAM_USER=hello YAAM_PASS=world ./yaam -``` diff --git a/docs/usage/PUBLISH.md b/docs/usage/PUBLISH.md deleted file mode 100644 index 4a0f658..0000000 --- a/docs/usage/PUBLISH.md +++ /dev/null @@ -1,5 +0,0 @@ -# Publish - -```bash -curl -X PUT localhost:25213/hello/world/hola.yaml --data-binary @blahblah.json -```