diff --git a/Jenkinsfile b/Jenkinsfile index c31d093c..bcfa3219 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -7,8 +7,7 @@ def notifyBranch = [recipients: [brokenTestsSuspects(), requestor()]] pipeline { agent { node { - label 'alpine:mkdocs' - customWorkspace workspace().getUniqueWorkspacePath() + label 'alpine-mkdocs' } } environment { @@ -21,14 +20,18 @@ pipeline { stage('Node') { steps { - nodeInfo("python pip mkdocs") + container("mkdocs") { + nodeInfo("python pip mkdocs") + } } } stage('Building') { steps { - withCredentials([string(credentialsId: '3ea1e18a-b1d1-44e0-a1ff-7b62870913f8', variable: 'GOOGLE_ANALYTICS_KEY')]) { - sh "mkdocs build" + container("mkdocs") { + withCredentials([string(credentialsId: '3ea1e18a-b1d1-44e0-a1ff-7b62870913f8', variable: 'GOOGLE_ANALYTICS_KEY')]) { + sh "mkdocs build" + } } } } @@ -37,21 +40,16 @@ pipeline { expression { BRANCH_NAME == 'master' && (currentBuild.result == null || currentBuild.result == 'SUCCESS') } } steps { - configFileProvider([configFile(fileId: 'e0235d92-c2fc-4f81-ae4b-28943ed7350d', targetLocation: '/tmp/gh-pages.sh')]) { - withCredentials([sshUserPrivateKey(credentialsId: '011f2a7d-2c94-48f5-92b9-c07fd817b4be', keyFileVariable: 'SSH_KEY', usernameVariable: 'SSH_USER')]) { - withEnv(["GIT_SSH_COMMAND=ssh -o StrictHostKeyChecking=no -o User=${SSH_USER} -i ${SSH_KEY}"]) { - sh "/bin/bash /tmp/gh-pages.sh" + container("mkdocs") { + configFileProvider([configFile(fileId: 'e0235d92-c2fc-4f81-ae4b-28943ed7350d', targetLocation: '/tmp/gh-pages.sh')]) { + withCredentials([sshUserPrivateKey(credentialsId: '011f2a7d-2c94-48f5-92b9-c07fd817b4be', keyFileVariable: 'SSH_KEY', usernameVariable: 'SSH_USER')]) { + withEnv(["GIT_SSH_COMMAND=ssh -o StrictHostKeyChecking=no -o User=${SSH_USER} -i ${SSH_KEY}"]) { + sh "/bin/bash /tmp/gh-pages.sh" + } } } } } } } - post { - cleanup { - script { - workspace().clean() - } - } - } } diff --git a/docker-compose.yml b/docker-compose.yml index e8f456d3..b6f3bd81 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,7 +1,7 @@ version: '3' services: mkdocs: - image: strongboxci/alpine:mkdocs-4.0 + image: strongboxci/alpine:mkdocs-4.4 volumes: - ./:/docs ports: diff --git a/docs/assets/resources/maven/settings-local.xml b/docs/assets/resources/maven/settings-local.xml new file mode 100644 index 00000000..190ad134 --- /dev/null +++ b/docs/assets/resources/maven/settings-local.xml @@ -0,0 +1,54 @@ + + + + .m2/repository-strongbox-local + + + + strongbox + strongbox + http://localhost:48080/storages/public/maven-group/ + * + + + + + + carlspring-repositories + + + true + + + + + strongbox + strongbox + http://localhost:48080/storages/public/maven-group/ + default + + + + + strongbox + strongbox + http://localhost:48080/storages/public/maven-group/ + default + + + + + + + + releases + admin + password + + + snapshots + admin + password + + + diff --git a/docs/developer-guide/building-strongbox-against-strongbox.md b/docs/developer-guide/building-strongbox-against-strongbox.md deleted file mode 100644 index ef6060cb..00000000 --- a/docs/developer-guide/building-strongbox-against-strongbox.md +++ /dev/null @@ -1,170 +0,0 @@ -# Building Strongbox against Strongbox - -We like our dog food and we try it all the time! :smiley: - -There will be many cases where you need to test things against either a full-blown Strongbox (via `strongbox-distribution`), -or the `strongbox-web-core`. The following article shows you how to do so. - -## Pre-requisites - -You will need to use the following Maven settings file (that we've called `settings-strongbox-localhost` and placed under `~/.m2/settings-strongbox-localhost`): - -``` - - - - - - strongbox - strongbox - http://localhost:48080/storages/public/public-group/ - * - - - - - - carlspring-repositories - - - true - - - - - strongbox - strongbox - http://localhost:48080/storages/public/public-group/ - default - - - - - strongbox - strongbox - http://localhost:48080/storages/public/public-group/ - default - - - - - - - - releases - admin - password - - - snapshots - admin - password - - - -``` - -This settings file will ensure that all required artifacts, plugins and extensions are resolved via the running instance -of Strongbox. In addition, it will override Maven Central as a fallback repository, so everything required will indeed -be resolved through `http://localhost:48080/storages/public/public-group/` which is a group repository that includes -all the hosted repositories in Strongbox, as well as all defined proxy repositories. - -## Building Strongbox Against The `strongbox-web-core` - -1. Checkout and build the `strongbox` project (either with `mvn clean install`, or `mvn clean install -DskipTests`, based on your needs) -2. In the `strongbox-web-core` module, execute the following in order to start Strongbox inside a Jetty instance waiting for connections: - ``` - mvn clean install spring-boot:run - ``` -3. In a separately checked out `strongbox` project execute: -``` -carlspring@carlspring:/java/strongbox> mvn -s ~/.m2/settings-strongbox-localhost.xml -Dmaven.repo.local=.m2/repository clean deploy -DaltDeploymentRepository=snapshots::default::http://localhost:48080/storages/storage0/snapshots/ -DskipTests -fn -... -[INFO] --- maven-install-plugin:2.4:install (default-install) @ strongbox-masterbuild --- -[INFO] Installing /java/strongbox/pom.xml to /java/strongbox/.m2/repository/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-SNAPSHOT.pom -[INFO] -[INFO] --- maven-deploy-plugin:2.7:deploy (default-deploy) @ strongbox-masterbuild --- -[INFO] Using alternate deployment repository snapshots::default::http://localhost:48080/storages/storage0/snapshots/ -Downloading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml -Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-20180128.060409-1.pom -Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-20180128.060409-1.pom (4 KB at 5.6 KB/sec) -Downloading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml -Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml -Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml (618 B at 1.2 KB/sec) -Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml -Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml (303 B at 0.6 KB/sec) -[INFO] ------------------------------------------------------------------------ -[INFO] Reactor Summary: -[INFO] -[INFO] Strongbox: Parent .................................. SUCCESS [01:03 min] -[INFO] Strongbox: Resources [Common] ...................... SUCCESS [01:59 min] -[INFO] Strongbox: Resources [Storage API] ................. SUCCESS [ 4.608 s] -[INFO] Strongbox: Resources [Web] ......................... SUCCESS [ 25.098 s] -[INFO] Strongbox: Resources ............................... SUCCESS [ 1.816 s] -... -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 13:37 min -[INFO] Finished at: 2018-01-28T06:04:10+00:00 -[INFO] Final Memory: 125M/1133M -[INFO] ------------------------------------------------------------------------ -``` - -## Building Strongbox Against A Full-blown Strongbox (`strongbox-distribution`) -1. Build `strongbox` like this: - ``` - mvn clean install -DskipTests - ``` -2. Go inside `./strongbox-distribution`: - ``` - cd strongbox-distribution/target - ``` -3. Extract the distribution archive: - ``` - tar -zxf *gz - ``` -4. Start Strongbox: - ``` - cd strongbox-distribution-*/strongbox-*/ - ./bin/strongbox console - ``` -5. Build the `strongbox` project against the running Strongbox instance: -``` -$ mvn clean deploy \ - -s ~/.m2/settings-strongbox-localhost.xml \ - -Dmaven.repo.local=.m2/repository \ - -DaltDeploymentRepository=snapshots::default::http://localhost:48080/storages/storage0/snapshots/ \ - -DskipTests \ - -fn -... -[INFO] --- maven-install-plugin:2.4:install (default-install) @ strongbox-masterbuild --- -[INFO] Installing /java/strongbox/pom.xml to /java/strongbox/.m2/repository/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-SNAPSHOT.pom -[INFO] -[INFO] --- maven-deploy-plugin:2.7:deploy (default-deploy) @ strongbox-masterbuild --- -[INFO] Using alternate deployment repository snapshots::default::http://localhost:48080/storages/storage0/snapshots/ -Downloading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml -Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-20180128.060409-1.pom -Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-20180128.060409-1.pom (4 KB at 5.6 KB/sec) -Downloading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml -Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml -Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml (618 B at 1.2 KB/sec) -Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml -Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml (303 B at 0.6 KB/sec) -[INFO] ------------------------------------------------------------------------ -[INFO] Reactor Summary: -[INFO] -[INFO] Strongbox: Parent .................................. SUCCESS [01:03 min] -[INFO] Strongbox: Resources [Common] ...................... SUCCESS [01:59 min] -[INFO] Strongbox: Resources [Storage API] ................. SUCCESS [ 4.608 s] -[INFO] Strongbox: Resources [Web] ......................... SUCCESS [ 25.098 s] -[INFO] Strongbox: Resources ............................... SUCCESS [ 1.816 s] -... -[INFO] ------------------------------------------------------------------------ -[INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -[INFO] Total time: 13:37 min -[INFO] Finished at: 2018-01-28T06:04:10+00:00 -[INFO] Final Memory: 125M/1133M -[INFO] ------------------------------------------------------------------------ -``` diff --git a/docs/developer-guide/building-strongbox-using-strongbox-instance.md b/docs/developer-guide/building-strongbox-using-strongbox-instance.md new file mode 100644 index 00000000..f0a60b27 --- /dev/null +++ b/docs/developer-guide/building-strongbox-using-strongbox-instance.md @@ -0,0 +1,101 @@ +{% set localSettingsXml = "~/.m2/settings-local.xml" %} + +# Building Strongbox using a Strongbox Instance + +We like our dog food and we try it all the time! :smiley: + +Working on Strongbox features is fun, but has a hidden issue - you can unintentionally break things. +The best way to know if your changes are not affecting Strongbox is by testing it in a real-world environment. +Building @strongbox/strongbox using a Strongbox instance is as "real world" environment as it can get and this +article goes into details how to do the testing. + +## Starting a Strongbox Instance + +Before you start testing, you will need to have a running Strongbox instance. + +You can start Strongbox in two ways - via `spring-boot` and from `strongbox-distribution`. In most cases, during the +development phase you will mainly start an instance via `spring-boot`. However once you are done with your task you +should always ensure the `strongbox-distribution` package works as expected. + +``` linenums="1" tab="Strongbox via spring-boot" +git clone {{repo_url}} +mvn clean install -DskipTests +cd strongbox-web-core +mvn spring-boot:run +``` + +``` linenums="1" tab="Strongbox from strongbox-distribution" +git clone {{repo_url}} +mvn clean install -DskipTests +cd strongbox-distribution/target +tar -zxf *gz +cd strongbox-distribution-*/strongbox-*/ +./bin/strongbox console +``` + +## Building and Deploying using Strongbox + +Following the steps below should result in successful result: + +1. [Did you pay attention?][Strongbox Instance] +2. Configure your `settings.xml` to point to the local [Strongbox Instance]: + + ``` tab="Download" + # Linux / MacOS + curl -o {{localSettingsXml}} \ + {{resources}}/maven/settings-local.xml + + # Windows + curl -o %HOMEPATH%\.m2\settings-local.xml ^ + {{resources}}/maven/settings-local.xml + ``` + + ``` tab="Raw/Copy" + --8<-- "{{resourcesPath}}/maven/settings-local.xml" + ``` + +3. Make a clean clone of @strongbox/strongbox into a separate path (i.e. `strongbox-tmp`) +4. Build Strongbox using a Strongbox instance: +``` +$ cd strongbox-tmp +$ mvn clean install -DskipTests -s {{localSettingsXml}} +... (should start downloading artifacts from localhost:48080 +[INFO] Scanning for projects... +Downloading from strongbox: http://localhost:48080/storages/public/maven-group/org/carlspring/strongbox/strongbox-parent/1.0-SNAPSHOT/maven-metadata.xml +Downloaded from strongbox: http://localhost:48080/storages/public/maven-group/org/carlspring/strongbox/strongbox-parent/1.0-SNAPSHOT/maven-metadata.xml (617 B at 1.7 kB/s) +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +``` + +5. Deploy into Strongbox +``` +$ mvn clean deploy \ + -s {{localSettingsXml}} + -DaltDeploymentRepository=snapshots::default::http://localhost:48080/storages/storage0/snapshots/ \ + -DskipTests \ + -fn + +... +[INFO] --- maven-install-plugin:2.4:install (default-install) @ strongbox-masterbuild --- +[INFO] Installing /java/strongbox-tmp/pom.xml to /java/strongbox-tmp/.m2/repository-strongbox-local/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-SNAPSHOT.pom +[INFO] +[INFO] --- maven-deploy-plugin:2.7:deploy (default-deploy) @ strongbox-masterbuild --- +[INFO] Using alternate deployment repository snapshots::default::http://localhost:48080/storages/storage0/snapshots/ +Downloading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml +Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-20180128.060409-1.pom +Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/strongbox-masterbuild-1.0-20180128.060409-1.pom (4 KB at 5.6 KB/sec) +Downloading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml +Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml +Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/1.0-SNAPSHOT/maven-metadata.xml (618 B at 1.2 KB/sec) +Uploading: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml +Uploaded: http://localhost:48080/storages/storage0/snapshots/org/carlspring/strongbox/strongbox-masterbuild/maven-metadata.xml (303 B at 0.6 KB/sec) +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +``` + + +[Strongbox Instance]: #starting-a-strongbox-instance diff --git a/mkdocs.yml b/mkdocs.yml index 77494680..eee1b329 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,8 +28,11 @@ plugins: extra: url: &url !!python/object/apply:os.getenv ["DEPLOY_URL", "http://localhost:8000"] - assets: !!python/object/apply:urllib.parse.urljoin [*url, "/assets"] - resources: !!python/object/apply:urllib.parse.urljoin [*url, "/assets/resources"] + assetsPath: &assetsPath "assets/" + resourcesPath: &resourcesPath !!python/object/apply:urllib.parse.urljoin [*assetsPath, "resources"] + assets: !!python/object/apply:urllib.parse.urljoin [*url, *assetsPath] + resources: !!python/object/apply:urllib.parse.urljoin [*url, *resourcesPath] + repo_url: "https://github.com/strongbox/strongbox" # Extensions markdown_extensions: @@ -54,10 +57,13 @@ markdown_extensions: - pymdownx.magiclink - pymdownx.mark - pymdownx.smartsymbols + - pymdownx.snippets: + base_path: docs - pymdownx.superfences - pymdownx.tasklist: custom_checkbox: true - pymdownx.tilde + - mdx_gh_links # Page tree nav: @@ -90,7 +96,7 @@ nav: - Building: - Building the code: developer-guide/building-the-code.md - Building the code (Docker): developer-guide/building-the-code-with-docker.md - - Building Strongbox against Strongbox: developer-guide/building-strongbox-against-strongbox.md + - Building Strongbox using a Strongbox instance: developer-guide/building-strongbox-using-strongbox-instance.md - IDE setup: - Eclipse: developer-guide/ide-setup/eclipse.md - Project structure: developer-guide/project-structure.md diff --git a/requirements.txt b/requirements.txt index 3c402a11..84177f5e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ -mkdocs-material==4.0.1 +mkdocs-material==4.4.2 mkdocs-markdownextradata-plugin mkdocs-git-revision-date-plugin +mdx_gh_links