Merge pull request #23 from 030/21-docs

docs: [#21] Describe how to configure and start YAAM.
030 · Sep 23, 2022 · 2e2062d · 2e2062d
2 parents 0a3f5da + 236f98b
commit 2e2062d
Show file tree

Hide file tree

Showing 18 changed files with 196 additions and 60 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -24,7 +24,7 @@ jobs:
           version=$(echo "${{ github.ref }}" | sed -e "s|.*\/\(.*\)$|\1|")
           echo "Version: ${version}"
           echo "Checking README.md..."
-          grep "yaam:${version}" docs/usage/DOCKER.md
+          grep "yaam:${version}" docs/start/DOCKER.md
           echo "Checking k8s-openshift deployment..."
           grep "yaam:${version}" deployments/k8s-openshift/deploy.yml
       - name: Create release

diff --git 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
@@ -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
@@ -2,6 +2,15 @@
 ## [Unreleased]
 
 
+<a name="v0.4.1"></a>
+## [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.
+
+
 <a name="v0.4.0"></a>
 ## [v0.4.0] - 2022-09-21
 ### Docs
@@ -28,7 +37,8 @@
 <a name="v0.2.1"></a>
 ## 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
@@ -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
@@ -0,0 +1,11 @@
+# generic
+
+## Configuration
+
+~/.yaam/conf/repositories/generic.yaml
+
+```bash
+---
+allowedRepos:
+  - something
+```
diff --git a/docs/usage/CONFIG.md → docs/config/MAVEN.md b/docs/usage/CONFIG.md → 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
@@ -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 → docs/preserve/MAVEN.md b/docs/usage/GRADLE.md → docs/preserve/MAVEN.md
@@ -1,7 +1,7 @@
-# Gradle
+# Maven
 
-## Cache artifacts
+## Gradle
 
 ```bash
 ./gradlew clean build
-```
+```
diff --git a/docs/preserve/NPM.md 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 → docs/publish/GENERIC.md b/docs/usage/GENERIC.md → 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
@@ -0,0 +1,7 @@
+# Maven
+
+## Gradle
+
+```bash
+./gradle publish
+```
diff --git a/docs/start/BINARY.md 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 → docs/start/DOCKER.md b/docs/usage/DOCKER.md → 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 → docs/start/K8SOPENSHIFT.md b/docs/usage/K8SOPENSHIFT.md → docs/start/K8SOPENSHIFT.md
diff --git a/docs/unify/MAVEN.md 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
diff --git a/docs/usage/PUBLISH.md b/docs/usage/PUBLISH.md