diff --git a/src/content/docs/administration/getting_started.md b/src/content/docs/administration/getting_started.md deleted file mode 100644 index b873201..0000000 --- a/src/content/docs/administration/getting_started.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Getting started ---- - -## System requirements - -### Operating system - -ArchivesSpace has been tested on Ubuntu Linux, Mac OS X, and Windows. - -### Memory - -At least 1024 MB RAM allocated to the application are required. We recommend using at least 2 GB for optimal performance. - -### Java Runtime Environment - -We recommend using [OpenJDK](https://openjdk.org/projects/jdk/). The following table lists the supported Java versions for each version of ArchivesSpace: - -| ArchivesSpace version | OpenJDK version | -| --------------------- | --------------- | -| ≤ v3.5.1 | 8 or 11 | -| ≥ v4.0.0 | 11 or 17 | - -### Solr - -Up to ArchivesSpace v3.1.1, the zip file distribution includes an embedded Solr v4 instance, which is deprecated and not supported anymore. - -ArchivesSpace v3.2.0 or above requires an external Solr instance. The table below summarizes the supported Solr versions for each ArchivesSpace version: - -| ArchivesSpace version | External Solr version | -| --------------------- | ------------------------- | -| ≤ v3.1.1 | no external solr required | -| v3.1.1 up to v3.5.1 | 8 (8.11) | -| ≥ v4.0.0 | 9 (9.4.1) | - -Each ArchivesSpace version is tested for compatibility with the corresponding Solr version listed in the table above. -That version is being used during development and the ArchivesSpace automated tests run with that version. It is therefore recommended that you use that version of Solr in production. - -It may be possible to use ArchivesSpace with an older version of Solr. However in that case it -is important to check the [release notes](https://github.com/archivesspace/archivesspace/releases) -for any potential version compatibility issues. - -**Note: the ArchivesSpace Program Team can only provide support for Solr deployments -using the "officially" supported version with the standard configuration provided by -the application. Everything else will be treated as "best effort" community-led support.** - -See [Running with external Solr](/provisioning/solr) for more information on installing and upgrading Solr. - -### Database - -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.) - -**The embedded database is for testing purposes only. You should use MySQL or MariaDB for any data intended for production, including data in a test instance that you intend to move over to a production instance.** - -All ArchivesSpace versions can run on MySQL version 5.x or 8.x. - -## Getting started - -The quickest way to get ArchivesSpace up and running is to download -the latest distribution `.zip` file from the following URL: - -[https://github.com/archivesspace/archivesspace/releases](https://github.com/archivesspace/archivesspace/releases) - -You will need to have Java installed on your machine. You can check your Java version by running the command: - - java -version - -See [above](#java-runtime-environment) for the Java version needed. If you are running an earlier version of java upgrade to one of the supported ones (not the newest one). If you are running a newer version of Java you should revert back to or force your machine to use a supported version. - -When you extract the `.zip` file, it will create a directory called -`archivesspace`. Next, follow the instructions for setting up: - -- [MySQL](/provisioning/mysql) -- for version 3.2 and above, [Solr](/provisioning/solr) 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.** - -**Do not proceed until MySQL and Solr are running.** - -To run the system, just execute the appropriate -startup script for your platform. On Linux and OSX: - - cd /path/to/archivesspace - ./archivesspace.sh - -and for Windows: - - cd \path\to\archivesspace - archivesspace.bat - -This will start ArchivesSpace running in foreground mode (so it will -shut down when you close your terminal window). Log output will be -written to the file `logs/archivesspace.out` (by default). - -**Note:** If you're running Windows and you get an error message like -`unable to resolve type 'size_t'` or `no such file to load -- bundler`, -make sure that there are no spaces in any part of the path name in which the -ArchivesSpace directory is located. - -### Start ArchivesSpace - -The first time it starts, the system will take a minute or so to start -up. Once it is ready, confirm that ArchivesSpace is running correctly by -accessing the following URLs in your browser: - -- http://localhost:8089/ -- the backend -- http://localhost:8080/ -- the staff interface -- http://localhost:8081/ -- the public interface -- http://localhost:8082/ -- the OAI-PMH server -- http://localhost:8090/ -- the Solr admin console - -To start using the Staff interface application, log in using the adminstrator -account: - -- Username: `admin` -- Password: `admin` - -Then, you can create a new repository by selecting "System" -> "Manage -repositories" at the top right hand side of the screen. From the -"System" menu, you can perform a variety of administrative tasks, such -as creating and modifying user accounts. **Be sure to change the -"admin" user's password at this time.** diff --git a/src/content/docs/development/docker.md b/src/content/docs/development/docker.md index 631362b..fe341e9 100644 --- a/src/content/docs/development/docker.md +++ b/src/content/docs/development/docker.md @@ -4,13 +4,6 @@ title: Docker The [Docker](https://www.docker.com/) configuration is used to create [automated builds](https://hub.docker.com/r/archivesspace/archivesspace/) on Docker Hub, which are deployed to [the latest version](http://test.archivesspace.org) when the build completes. -Please note: - -- Docker is not supported as an install method. -- Docker configuration is being used for internal purposes only. -- Use of Docker by anyone else is "use at your own risk". -- Docker related files may be updated at anytime without warning or presence in release notes. - ## Custom builds Run ArchivesSpace with MySQL, external Solr and a Web Proxy. Switch to the diff --git a/src/content/docs/getting_started/docker.md b/src/content/docs/getting_started/docker.md new file mode 100644 index 0000000..dc2e36a --- /dev/null +++ b/src/content/docs/getting_started/docker.md @@ -0,0 +1,50 @@ +--- +title: Running ArchivesSpace using Docker +--- + +# Installing + +The easiest way to get ArchivesSpace up and running is by using [Docker](https://www.docker.com/). Using docker eases installing, upgrading, starting and stopping ArchivesSpace. +It also makes it easy to have ArchivesSpace running as a system service that starts automatically on every reboot. + +If you prefer not to use Docker, another (more involved ) way to get ArchivesSpace up and running is installing the latest [distribution `.zip` file](/getting_started/zip_distribution). + +## System requirements + +See [System Requirements](/getting_started/system_requirements) + +## Software Dependencies + +When using Docker, the only software dependency is [Docker](https://www.docker.com/). + +Follow the [instructions](https://docs.docker.com/get-started/get-docker/) to install the docker engine. Optionally installing [Docker Desktop](https://www.docker.com/products/docker-desktop/) provides a UI to manage, start and stop your docker containers + +## Downloading the configuration package + +To run ArchivesSpace with Docker: + +TODO: fix links after merging: https://github.com/archivesspace/archivesspace/pull/3420 + +- Download the [ArchivesSpace docker configuration package](https://download-directory.github.io/?url=https%3A%2F%2Fgithub.com%2Farchivesspace%2Farchivesspace%2Ftree%2Fmaster%2Fclustering%3F&filename=archivesspace). The contents of the download are zipped from [this directory](https://github.com/archivesspace/archivesspace/tree/master/clustering) of our github repository. + +* Unzipping the downloaded file will give the following structure: + - Configuration + - plugins + +## Start + +Starting with the `--detach` option allows closing the terminal without stoping ArchivesSpace + +```bash +docker compose up --detach +``` + +The first time it starts, the system will take a minute or so to start up. You can then [login and verify](/getting_started/first_steps) that it is running correctly. + +## View logs + +## Stop + +## Using Docker Desktop + +# Upgrading diff --git a/src/content/docs/getting_started/first_steps.md b/src/content/docs/getting_started/first_steps.md new file mode 100644 index 0000000..8231e34 --- /dev/null +++ b/src/content/docs/getting_started/first_steps.md @@ -0,0 +1,19 @@ +--- +title: First Steps +--- + +Once it is ready, confirm that ArchivesSpace is running correctly by accessing the following URLs in your browser: + +- http://localhost:8089/ -- the backend +- http://localhost:8080/ -- the staff interface +- http://localhost:8081/ -- the public interface +- http://localhost:8082/ -- the OAI-PMH server +- http://localhost:8090/ -- the Solr admin console + +To start using the Staff interface application, log in using the administrator account: + +- Username: `admin` +- Password: `admin` + +Then, you can create a new repository by selecting "System" -> "Manage repositories" at the top right hand side of the screen. From the "System" menu, you can perform a variety of administrative tasks, +such as creating and modifying user accounts. **Be sure to change the "admin" user's password at this time.** diff --git a/src/content/docs/getting_started/overview.md b/src/content/docs/getting_started/overview.md new file mode 100644 index 0000000..176af74 --- /dev/null +++ b/src/content/docs/getting_started/overview.md @@ -0,0 +1,5 @@ +--- +title: Getting started +--- + +you can use docker or the zip distribution diff --git a/src/content/docs/getting_started/system_requirements.md b/src/content/docs/getting_started/system_requirements.md new file mode 100644 index 0000000..192178d --- /dev/null +++ b/src/content/docs/getting_started/system_requirements.md @@ -0,0 +1,11 @@ +--- +title: System requirements +--- + +## Operating system + +ArchivesSpace is known to operate well on Ubuntu Linux, Mac OS X, and Windows. + +## Memory + +At least 1024 MB RAM allocated to the application are required. We recommend using at least 2 GB for optimal performance. diff --git a/src/content/docs/getting_started/zip_distribution.md b/src/content/docs/getting_started/zip_distribution.md new file mode 100644 index 0000000..0738d53 --- /dev/null +++ b/src/content/docs/getting_started/zip_distribution.md @@ -0,0 +1,87 @@ +--- +title: Running ArchivesSpace using the zip distribution (without Docker) +--- + +If you prefer not to [use Docker](/getting_started/docker.md), another way to get ArchivesSpace up and running is to download the latest distribution `.zip` +file and use your own-managed Database and Solr services. This requires more effort to get all requirements in place, as explained below. + +## System requirements + +See [System Requirements](/getting_started/system_requirements) + +## Software Dependencies + +When using the zip distribution of ArchivesSpace, the following software dependencies are required: + +### Java Runtime Environment + +You will need to have Java installed on your machine. You can check your Java version by running the command: + + java -version + +We recommend using [OpenJDK](https://openjdk.org/projects/jdk/). The following table lists the supported Java versions for each version of ArchivesSpace: + +| ArchivesSpace version | OpenJDK version | +| --------------------- | --------------- | +| ≤ v3.5.1 | 8 or 11 | +| ≥ v4.0.0 | 11 or 17 | + +If you are running an earlier version of java upgrade to one of the supported ones (not the newest one). If you are running a newer version of Java you should revert back to or force your machine to use a supported version. + +### Solr + +Up to ArchivesSpace v3.1.1, the zip file distribution includes an embedded Solr v4 instance, which is deprecated and not supported anymore. + +ArchivesSpace v3.2.0 or above requires an external Solr instance. The table below summarizes the supported Solr versions for each ArchivesSpace version: + +| ArchivesSpace version | External Solr version | +| --------------------- | ------------------------- | +| ≤ v3.1.1 | no external solr required | +| v3.1.1 up to v3.5.1 | 8 (8.11) | +| ≥ v4.0.0 | 9 (9.4.1) | + +Each ArchivesSpace version is tested for compatibility with the corresponding Solr version listed in the table above, both during development and automated testing. + +It may be possible to use ArchivesSpace with an older version of Solr. However in that case it is important to check the [release notes](https://github.com/archivesspace/archivesspace/releases) +for any potential version compatibility issues. + +**Note: the ArchivesSpace Program Team can only provide support for Solr deployments using the "officially" supported version with the standard configuration provided by +the application. Everything else will be treated as "best effort" community-led support.** + +See [Running with external Solr](/provisioning/solr) for more information on installing and upgrading Solr. + +### Database + +While the ArchivesSpace zip distribution does include an embedded database for demonstration purposes, 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.) + +**The embedded database is for testing purposes only. You should use MySQL or MariaDB for any data intended for production, including data in a test instance that you intend to move over to +a production instance.** + +All ArchivesSpace versions can run on MySQL version 5.x or 8.x. See [MySQL](/provisioning/mysql) for detailed instructions on setting up MySQL for ArchivesSpace. + +## Downloading and Installing + +Once you have Java, MySQL and Solr in place, you are ready to download and install ArchivesSpace. **Do not proceed until MySQL and Solr are running.** The latest version of the ArchivesSpace zip distribution (and all older ones) are available at: [https://github.com/archivesspace/archivesspace/releases](https://github.com/archivesspace/archivesspace/releases) + +When you extract the `.zip` file, it will create a directory called `archivesspace`. + +It is now time to download and install the [JDBC driver for MySQL](https://docs.archivesspace.org/provisioning/mysql/#download-mysql-connector). + +### Start ArchivesSpace + +To run the system, just execute the appropriate startup script for your platform. On Linux and OSX: + + cd /path/to/archivesspace + ./archivesspace.sh + +and for Windows: + + cd \path\to\archivesspace + archivesspace.bat + +This will start ArchivesSpace running in foreground mode (so it will shut down when you close your terminal window). Log output will be written to the file `logs/archivesspace.out` (by default). + +**Note:** If you're running Windows and you get an error message like `unable to resolve type 'size_t'` or `no such file to load -- bundler`,make sure that there are no spaces in any part of the +path name in which the ArchivesSpace directory is located. + +The first time it starts, the system will take a minute or so to start up. You can then [login and verify](/getting_started/first_steps) that it is running correctly. diff --git a/src/siteNavigation.json b/src/siteNavigation.json index 7dd2a22..5e379e0 100644 --- a/src/siteNavigation.json +++ b/src/siteNavigation.json @@ -5,11 +5,18 @@ }, { "label": "Getting started", - "link": "administration/getting_started" + "collapsed": false, + "items": [ + "getting_started/overview", + "getting_started/system_requirements", + "getting_started/docker", + "getting_started/zip_distribution", + "getting_started/first_steps" + ] }, { "label": "Architecture", - "collapsed": false, + "collapsed": true, "items": [ "architecture/jsonmodel", "architecture/backend",