| title | Running with Docker |
|---|---|
| description | Instructions on setting up, running, and managing an ArchivesSpace installation using Docker. |
Starting with v4.0.0 ArchivesSpace officially supports using Docker as the easiest way to get up and running. Docker eases installing, upgrading, starting and stopping ArchivesSpace. It also makes it easy to setup ArchivesSpace 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.
ArchivesSpace Docker images are available on the Docker hub.
- main application images are built from this Dockerfile
- solr images are built from this Dockerfile
ArchivesSpace on Docker has been tested on Ubuntu Linux, Mac OS X, and Windows. At least 1024 MB RAM are required. We recommend using at least 2 GB for optimal performance.
When using Docker, the only software dependency is Docker itself. Follow the instructions to install the Docker engine. Optionally installing Docker Desktop provides a graphical way to manage, start and stop your docker containers, easily review the container logs etc.
To run ArchivesSpace with Docker, first download the ArchivesSpace docker configuration package of the latest release from github (scroll down to the "Assets" section of the latest release page and look for the zip file named archivesspace-docker-${VERSION}.zip).
The downloaded configuration package contains a simple yet configurable and production ready docker-based setup intended to run on a single computer.
Unzipping the downloaded file will create an archivesspace directory with the following contents:
.
├── backups
├── config
│ └── config.rb
├── locales
├── plugins
├── proxy-config
│ └── default.conf
├── sql
├── docker-compose.yml
├── stylesheets
└── .env
- The
backupsdirectory is first created once you start the application and it will contain the automatically performed backups of the database. See Automated Backups section. config/config.rbfile contains the main configuration of ArchivesSpace.- The
localesdirectory allows customization of the UI text. - The
pluginsdirectory is there to accommodate additional ArchivesSpace plugins. By default, it contains thelocalandlcnafplugins. proxy-config/default.confcontains the configuration of the bundlednginxsee also proxy configuration.- In the
sqldirectory you can put your.sqldatabase dump file to initialize the new database, see next section. - The
stylesheetsdirectory contain the files that are used to create PDFs and other files. docker-compose.ymlcontains all the information required by Docker to build and run ArchivesSpace..envcontains configuration of the docker containers including:- Credentials used by archivespace to access its MySQL database. It is recommended to change the default root and user passwords to something safer.
- The database connection URI which should also be updated accordingly after the database user password is updated in the step above.
If you are currently running ArchivesSpace using the zip file distribution, you can start using Docker instead.
Use mysqldump to create a dump of your MySQL database:
mysqldump -uroot -p123456 -h 127.0.0.1 archivesspace > /tmp/db.$(date +%F.%H%M%S).sqlFollow the steps under the Backup and recovery section if you need more instructions on how create backups of your MySQL database.
Copy your .sql database dump file created above in the sql directory of your unzipped Docker configuration package. Make sure the filename includes the .sql extension. The file should be in plain text format (not zipped).
Docker will pick it up when it starts for the first time and restore the dump to your new database.
If you created the dump on an earlier ArchivesSpace version, the system will apply any pending database migrations to upgrade your database to the ArchivesSpace version you are currently running on Docker.
After the initial run you will want to remove that .sql file from the sql directory of your unzipped Docker configuration package.
The docker configuration package already includes a configurable database backup mechanism for MySQL. Read more about it in the backup and recovery section.
We recommend allocating at least 2GB per container for optimal performance. If the host instance is devoted to running ArchivesSpace, it is advisable to configure no memory limit for Docker containers.
When using Docker Desktop, a default memory limit is set to 50% of your host's memory. To increase the RAM and other resource limits when using Docker Desktop, see the documentation.
When using Docker without Docker Desktop, no memory limit is set by default. See Docker documenentation if you need to set limits to the resources used by ArchivesSpace containers.
If migrating from the zip distribution to Docker, you most probably have local MySQL and Solr instances running. Starting ArchivesSpace with Docker will start Docker-based MySQL and Solr instances. In order to avoid port binding conflicts, make sure that you stop your local MySQL and Solr instances before proceeding.
Open a terminal, change to the archivespace directory that contains the docker-compose.yml file and run:
docker compose up --detachThe first time you start ArchivesSpace with Docker, the container images will be downloaded and configuration steps such as database setup and solr index initialization will be performed automatically.
It is expected that the whole process takes up to ten or even more minutes depending on the power of your machine and internet connection speed. Note if you are migrating from using the zip distribution to Docker and have already copied a dump of your database in the sql directory, initialization of the database and indexing it in solr can take a long time depending on the size of your data.
Starting with the --detach option allows closing the terminal without stopping ArchivesSpace. Viewing the logs of running ArchivesSpace containers is possible in Docker Desktop or in a terminal with:
docker compose logs --followWatch the logs for the welcome message:
2024-12-04 18:42:17 archivesspace | ************************************************************
2024-12-04 18:42:17 archivesspace | Welcome to ArchivesSpace!
2024-12-04 18:42:17 archivesspace | You can now point your browser to http://localhost:8080
2024-12-04 18:42:17 archivesspace | ************************************************************
Using the default proxy configuration, the Public User interface becomes available at http://localhost/ and the Staff User Interface at: http://localhost/staff/ (default login with: admin / admin)
You can see the status of your running containers with:
docker ps
Which will give a listing like this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6cd7114c1796 nginx:1.21 "/docker-entrypoint.…" 26 hours ago Up 29 minutes 0.0.0.0:80->80/tcp, :::80->80/tcp proxy
9ed453c46a9f archivesspace/archivesspace:4.0.0 "/archivesspace/star…" 26 hours ago Up 29 minutes (healthy) 8080-8081/tcp, 8089-8090/tcp, 8092/tcp archivesspace
ec71dd3030b7 databack/mysql-backup:latest "/entrypoint dump" 26 hours ago Up 29 minutes db-backup
8b74aa374ec8 archivesspace/solr:4.0.0 "docker-entrypoint.s…" 26 hours ago Up 29 minutes 0.0.0.0:8983->8983/tcp, :::8983->8983/tcp solr
d2cf634744fe mysql:8 "docker-entrypoint.s…" 26 hours ago Up 29 minutes 0.0.0.0:3306->3306/tcp, :::3306->3306/tcp, 33060/tcp mysql
If you have also Docker Desktop installed, you can use it to start, stop and manage the ArchivesSpace containers after they have been created for the first time. Docker Desktop does have a built in terminal window that can be used to run Docker commands.
The following commands need to run from archivespace directory that contains the docker-compose.yml file. You can stop running containers (without deleting) them with the command:
docker compose stopThey can be started again with:
docker compose up --detachYou can get a bash shell on the container running the archivespace application and run the any of the scripts in the scripts directory with:
$ docker exec -it archivesspace bash
archivesspace@9ed453c46a9f:/$ cd archivesspace/scripts/
archivesspace@9ed453c46a9f:/archivesspace/scripts$ ls
backup.bat backup.sh ead_export.bat ead_export.sh find-base.sh initialize-plugin.bat initialize-plugin.sh password-reset.bat password-reset.sh rb setup-database.bat setup-database.sh
archivesspace@9ed453c46a9f:/archivesspace/scripts$ ./setup-database.sh
NOTE: Picked up JDK_JAVA_OPTIONS: --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED
Loading ArchivesSpace configuration file from path: /archivesspace/config/config.rb
Loading ArchivesSpace configuration file from path: /archivesspace/config/config.rb
Loading ArchivesSpace configuration file from path: /archivesspace/config/config.rb
Detected MySQL connector 8+
Running migrations against jdbc:mysql://db:3306/archivesspace?useUnicode=true&characterEncoding=UTF-8&user=[REDACTED]&password=[REDACTED]&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
All done.The archivespace data directory is not exposed in the Docker Configuration package (as are locales, config, and locales making them easily accessible). This is due to issues we have had on Windows when exposing
the data directory instead of using a Docker volume for it.
If you need to copy files from/to the data directory, or any other directory of the archivesspace installation, you can use docker cp commands, such as:
docker cp archivesspace:/archivesspace/data/indexer_state /tmp/indexer_state
docker cp ~/Desktop/test.png archivesspace:/archivesspace/dataThe Docker configuration package includes a mechanism that will perform periodic backups of your MySQL database, see the Backup and Recovery for more information.
The Docker configuration package includes an nginx based proxy that is by default binding on port 80 of the host machine (see NGINX_PORT variable in .env file). See proxy-config/default.conf and the nginx docker page for more configuration options.
If you are already using the Docker configuration package and upgrading to a newer ArchivesSpace version, download and extract the latest version of the Docker configuration package.
If the ArchivesSpace version you are upgrading to includes solr configuration or schema changes (see the release notes), then you need to recreate your solr core and re-index. Change to the archivespace directory where you extraced the fresh downloaded Docker configuration package and run:
docker compose down solr app
docker volume rm archivesspace_app-data archivesspace_solr-data
docker compose pull
docker compose up -d --build --force-recreateIf no solr configuration or schema changes are included, change to the extracted architecture directory and run:
docker compose pull
docker compose up -d --build --force-recreate