Merge branch 'master' into solr-v9-support

.github/workflows/jekyll.yml

@@ -0,0 +1,63 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@8575951200e472d5f2d95c625da0c7bec8217c42 # v1.161.0
+        with:
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Run Cypress tests
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true # runs 'bundle install'
+
+      - name: Set up Node.js
+        uses: actions/[email protected]
+        with:
+          node-version-file: 'package.json'
+
+      - name: Cypress run
+        uses: cypress-io/github-action@v6 # runs 'npm ci'
+        with:
+          start: npm start
+          wait-on: 'http://localhost:4000'

.gitignore

@@ -3,3 +3,4 @@
 /*/.DS_Store
 _site
 .jekyll-cache
+node_modules

.npmrc

@@ -0,0 +1 @@
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+20.17

.ruby-version

@@ -0,0 +1 @@
+3.2.0

CYPRESS.md

@@ -0,0 +1,88 @@
+# Run the Cypress end-to-end test suite
+
+Running the Cypress tests depends on:
+
+- Ruby for building and serving the site
+- Node.js for running Cypress while the site is being served
+
+This documentation assumes your machine has git installed and GitHub credentials configured. See the git [Downloads page](https://git-scm.com/downloads) for help installing git, and [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for help configuring shell access to GitHub.
+
+## Clone this repo
+
+First clone this repository to your machine then move into it:
+
+```sh
+git clone [email protected]:archivesspace/tech-docs.git
+
+cd tech-docs
+```
+
+**All of the remaining commands within this document should be run from the tech-docs root directory.**
+
+## Setup the Ruby environment
+
+The currently required Ruby version for this project is listed in the [.ruby-version](./.ruby-version) file.
+
+It is strongly recommended to use a Ruby version manager to be able to switch to any version that a given project uses.
+
+The most popular version manager available for macOS and Linux is `rbenv`. You can find the installation guide here [https://github.com/rbenv/rbenv#readme](https://github.com/rbenv/rbenv#readme).
+
+For Windows, a separate `rbenv` installer exists here: [https://github.com/RubyMetric/rbenv-for-windows#readme](https://github.com/RubyMetric/rbenv-for-windows#readme).
+
+If you wish to use a different manager or installation method, you can choose one of the following: [https://www.ruby-lang.org/en/documentation/installation/](https://www.ruby-lang.org/en/documentation/installation/)
+
+### Install Ruby
+
+Install Ruby using `rbenv`:
+
+```sh
+rbenv install
+```
+
+### Install Ruby gems
+
+Install the project specific Ruby dependencies listed in [Gemfile](./Gemfile) which are used for building and serving the site.
+
+```sh
+bundle install
+```
+
+## Set up the Node.js environment
+
+The currently required Node.js version for this project is listed in [.nvmrc](./.nvmrc) and under the `engines.node` key in [package.json](./package.json).
+
+It is strongly recommended to use a Node.js version manager to be able to switch to any version that a given project uses.
+
+The most popular version manager available for macOS and Linux is `nvm`. You can find the installation guide here [https://github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm).
+
+A popular version manager for Windows is `nvm-windows`. See the installation guide here [https://github.com/coreybutler/nvm-windows](https://github.com/coreybutler/nvm-windows).
+
+### Install Node.js
+
+Install Node.js using `nvm`:
+
+```sh
+nvm install
+```
+
+### Install Node modules
+
+Install the project specific Node dependencies listed in [package.json](./package.json) which are used for running the tests:
+
+```sh
+npm install
+```
+
+## Run the tests locally
+
+Run the tests localy by first serving the site:
+
+```sh
+npm start
+```
+
+Then **in a different terminal** initiate the tests:
+
+```sh
+npm test
+```

Gemfile.lock

@@ -62,13 +62,16 @@ GEM
     safe_yaml (1.0.5)
     sass-embedded (1.58.0-arm64-darwin)
       google-protobuf (~> 3.21)
+    sass-embedded (1.58.0-x86_64-linux-gnu)
+      google-protobuf (~> 3.21)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
     unicode-display_width (2.4.2)
     webrick (1.8.1)
 
 PLATFORMS
   arm64-darwin-21
+  x86_64-linux
 
 DEPENDENCIES
   http_parser.rb (~> 0.6.0)

README.md

@@ -6,9 +6,9 @@ permalink: /
 
 The technical documentation covers a range of topics of interest to those working with ArchivesSpace in different technical capacities, and is organized in order to help you find the information most appropriate to your role.
 
-- **[ArchivesSpace technical overview](./readme_evaluate.md)** – For anyone who needs to evaluate technical requirements and capabilities of ArchivesSpace
-- **[Installing, configuring and maintaining an ArchivesSpace instance](./readme_implement.md)** – For anyone responsible for installing and/or maintaining an ArchivesSpace instance
-- **[Developer resources](./readme_develop.md)** – For anyone who needs to create plugins, integrate ArchivesSpace with other systems, or contribute to core code
+- **[ArchivesSpace technical overview](./readme_evaluate)** – For anyone who needs to evaluate technical requirements and capabilities of ArchivesSpace
+- **[Installing, configuring and maintaining an ArchivesSpace instance](./readme_implement)** – For anyone responsible for installing and/or maintaining an ArchivesSpace instance
+- **[Developer resources](./readme_develop)** – For anyone who needs to create plugins, integrate ArchivesSpace with other systems, or contribute to core code
 
 **To suggest corrections or additions, please submit a pull request or issue report on [Github](https://github.com/archivesspace/tech-docs)**
 

_config.yml

@@ -17,9 +17,18 @@ defaults:
     values:
       layout: "default"
 
+exclude:
+  - cypress/
+  - CYPRESS.md
+  - package*.json
+  - LICENSE
+
 github: # recreate gh-pages api
   is_project_page: true
   repository_url: https://github.com/archivesspace/tech-docs
   repository_nwo: archivesspace/tech-docs
   owner_url: https://github.com/archivesspace
   owner_name: ArchivesSpace
+  edit_base_url: https://github.com/archivesspace/tech-docs/edit/master/
+
+jira_issues: https://archivesspace.atlassian.net/jira/software/projects/TD/issues

_layouts/default.html

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: "en-US" }}">
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+{% seo %}
+    <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
+    <!--[if lt IE 9]>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
+    <![endif]-->
+    {% include head-custom.html %}
+  </head>
+  <body>
+    <div class="wrapper">
+      <header>
+        <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repository_name }}</a></h1>
+
+        {% if site.logo %}
+          <img src="{{site.logo | relative_url}}" alt="Logo" />
+        {% endif %}
+
+        <p>{{ site.description | default: site.github.project_tagline }}</p>
+
+        {% if site.github.is_project_page %}
+        <p class="view"><a href="{{ site.github.repository_url }}">View the Project on GitHub <small>{{ site.github.repository_nwo }}</small></a></p>
+        {% endif %}
+
+        {% if site.github.is_user_page %}
+        <p class="view"><a href="{{ site.github.owner_url }}">View My GitHub Profile</a></p>
+        {% endif %}
+
+        {% if site.show_downloads %}
+        <ul class="downloads">
+          <li><a href="{{ site.github.zip_url }}">Download <strong>ZIP File</strong></a></li>
+          <li><a href="{{ site.github.tar_url }}">Download <strong>TAR Ball</strong></a></li>
+          <li><a href="{{ site.github.repository_url }}">View On <strong>GitHub</strong></a></li>
+        </ul>
+        {% endif %}
+
+        <p>
+          <a
+            href="{{ site.github.edit_base_url }}{{ page.path }}"
+            title="Edit {{ page.path }} on GitHub"
+          >
+            Edit this page on GitHub
+            <small>{{ page.path }}</small>
+          </a>
+        </p>
+
+        <p>
+          <a
+            href="{{ site.jira_issues }}"
+            title="Report issue with {{ page.path }} on Jira"
+          >
+            Report issue on Jira
+            <small>{{ page.path }}</small>
+          </a>
+        </p>
+      </header>
+      <section>
+
+      {{ content }}
+
+      </section>
+      <footer>
+        {% if site.github.is_project_page %}
+        <p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
+        {% endif %}
+        <p><small>Hosted on GitHub Pages &mdash; Theme by <a href="https://github.com/orderedlist">orderedlist</a></small></p>
+      </footer>
+    </div>
+    <script src="{{ "/assets/js/scale.fix.js" | relative_url }}"></script>
+  </body>
+</html>

administration/getting_started.md

@@ -5,10 +5,11 @@
 * Java 8 or 11 only (OpenJDK should be fine)
 * At least 1024 MB RAM allocated to the application; at least 2 GB for optimal performance.
 * Solr (for ArchivesSpace versions after 3.1)
+* NodeJS
 
 ArchivesSpace has been tested on Ubuntu Linux, Mac OS X, and Windows.
 
-While ArchivesSpace does include an embedded database, MySQL is required for production use. 
+While ArchivesSpace does include an embedded database, MySQL is required for production use.
 
 (While not officially supported by ArchivesSpace, some community members use MariaDB so there is some community support for version 10.4.10 only.)
 
@@ -29,8 +30,11 @@ You can check your Java version by running the command:
 If you are running an earlier version of java upgrade to 1.8 or 1.11 (not the newest version of Java). If you are running a newer version of Java you should revert back to 1.8 or 1.11 or force your machine to use 1.8 or 1.11 for ArchivesSpace.
 
 When you extract the `.zip` file, it will create a directory called
-`archivesspace`. Next, follow the instructions for setting up
-[MySQL](../provisioning/mysql.html), and for version 3.2 and above, [Solr](../provisioning/solr.html).
+`archivesspace`. Next, follow the instructions for setting up:
+
+* [MySQL](../provisioning/mysql.html)
+* The minimum supported version is v18.20.2. We recommend installing the latest LTS version of Node.js. See the [Node.js download page](https://nodejs.org/en/download/) for instructions.
+* for version 3.2 and above, [Solr](../provisioning/solr.html) is also required
 
 **From any ArchivesSpace version > 3.1.0 external Solr is required. Earlier versions provided an embedded Solr v4 instance, which is now unsupported due to its age.**
 

administration/upgrading.md

@@ -127,7 +127,7 @@ Or on Windows:
 
 ## If you're using external Solr (required beginning with version 3.2.0)
 
-[Full instructions for using external Solr with ArchivesSpace](provisioning/solr.html)
+[Full instructions for using external Solr with ArchivesSpace](https://archivesspace.github.io/tech-docs/provisioning/solr.html)
 
 
 ## If you've deployed to Tomcat

customization/authentication.md

@@ -4,8 +4,8 @@ ArchivesSpace supports LDAP-based authentication out of the box, but you can
 authenticate against other password-based user directories by defining your own
 authentication handler, creating a plug-in, and configuring your ArchivesSpace
 instance to use it.  If you would rather not have to create your own handler,
-there is a plug-in available that uses OAUTH user authentication that you can add
-to your ArchivesSpace installation: https://github.com/lyrasis/aspace-oauth.
+there is a [plug-in](https://github.com/lyrasis/aspace-oauth) available that uses OAUTH user authentication that you can add
+to your ArchivesSpace installation.
 
 ## Creating a new authentication handler class to use in a plug-in
 

customization/configuration.md

@@ -18,7 +18,7 @@ ArchivesSpace. Be sure that your new settings are not commented out
 Set your database name and credentials. The default specifies that the embedded database should be used.
 It is recommended to use a MySQL database instead of the embedded database.
 For more info, see
-[Running ArchivesSpace against MySQL](https://github.com/archivesspace/tech-docs/blob/master/provisioning/mysql.html)
+[Running ArchivesSpace against MySQL](https://archivesspace.github.io/tech-docs/provisioning/mysql.html)
 
 This is an example of specifying MySQL credentials:
 
@@ -177,7 +177,6 @@ Directory to store Solr backups.
 
 `AppConfig[:solr_backup_directory] = proc { File.join(AppConfig[:data_directory], "solr_backups") }`
 
-
 ### Default Solr params
 
 #### `AppConfig[:solr_params]`

cypress.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents() {}
+  }
+});