Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ANW-2218 update docker docs #221

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

ANW-2218 update docker docs #221

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0a0be10
ANW-2218 update docker docs
thimios Jan 29, 2025
36501de
Merge branch 'main' into docker-docs-update
brianzelip Jan 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 33 additions & 18 deletions src/content/docs/administration/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Running with Docker

## Docker images

Starting with v4.0.0 ArchivesSpace officially supports using [Docker](https://www.docker.com/) as the easiest way to get ArchivesSpace 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.
Starting with v4.0.0 ArchivesSpace officially supports using [Docker](https://www.docker.com/) 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](/getting_started/zip_distribution).

Expand All @@ -22,31 +22,38 @@ See [System Requirements](/administration/getting_started/#system-requirements).
### Software Dependencies

When using Docker, the only software dependency is [Docker](https://www.docker.com/) itself. 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 graphical way to manage, start and stop your docker containers.
Optionally installing [Docker Desktop](https://www.docker.com/products/docker-desktop/) provides a graphical way to manage, start and stop your docker containers, easily review the container logs etc.

### Downloading the configuration package

To run ArchivesSpace with Docker, first download the ArchivesSpace docker configuration package of the latest release from [github](https://github.com/archivesspace/archivesspace/releases) (scroll down to the "Assets" section of the latest release page).

Unzipping the downloaded file will create an `archivespace-docker-vX.X.X` directory with the following contents:
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
├── docker-compose.yml
├── .env.docker.db
├── .env.docker.prod
├── plugins
└── sql
├── proxy-config
│   └── default.conf
├── sql
├── docker-compose.yml
└── .env
```

- The `config.rb` file contains the [main configuration](/customization/configuration/) of ArchivesSpace.
- The `backups` directory is actually automatically created once you start the application and it will contain the automatically performed backups of the database. See [Automated Backups section](#automated-database-backups).
- `config/config.rb` file contains the [main configuration](/customization/configuration/) of ArchivesSpace.
- The `plugins` directory is there to accommodate additional ArchivesSpace [plugins](/customization/plugins/)
- `proxy-config/default.conf` contains the configuration of the bundled `nginx` see also [proxy configuration](#proxy-configuration).
- In the `sql` directory you can put your `.sql` database dump file to initialize the new database, see [next section](migrating-from-the-zip-distribution-to-docker).
- `docker-compose.yml` contains all the information required by Docker to build and run ArchivesSpace.
- `.env.docker.db` contains the credentials used by archivespace to access its MySQL database. It is recommended to change the default root and user passwords to something safer.
- `.env.docker.prod` contains the database connection URI which should also be [updated accordingly](/customization/configuration/#database-config) after the database user password is updated in the step above.
- The `plugins` directory is there to accommodate any [plugins](/customization/plugins/) you wish to install.
- In the `sql` directory you can put your `.sql` database dump file to initialize the new database, see next section.
- `.env` contains 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](/customization/configuration/#database-config) after the database user password is updated in the step above.

## Migrating from the zip distribution to docker

Expand All @@ -64,7 +71,7 @@ Follow the steps under the [Backup and recovery](/administration/backup/) sectio

### Initialize and migrate the database on Docker

Copy your `.sql` database dump created above in the `sql` directory of your unzipped Docker configuration package. Make sure the file has the `.sql` extension and is in plain text format (not zipped).
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.
Expand All @@ -73,14 +80,14 @@ If you created the dump on an earlier ArchivesSpace version, the system will app

### Start

Open a terminal, change to the `archivespace-docker-vX.X.X` directory that contains the `docker-compose.yml` file and run:
Open a terminal, change to the `archivespace` directory that contains the `docker-compose.yml` file and run:

```
docker compose up --detach
```

The 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 minutes or even more 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.
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](https://www.docker.com/products/docker-desktop/) or in a terminal with:

Expand All @@ -97,13 +104,13 @@ Watch the logs for the welcome message:
2024-12-04 18:42:17 archivesspace | ************************************************************
```

You can then [login and verify](/administration/getting_started/#start-archivesspace) that it is running correctly.
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)

If you have also [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed, you can use it to start, stop and manage the ArchivesSpace containers after they have been created for the first time. At the time of writing this, there is no way to call `docker compose` using Docker Desktop, it has to be called on a terminal as described above.

### Stop

You can stop running containers without removing them with the command:
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 stop
Expand All @@ -112,5 +119,13 @@ docker compose stop
They can be started again with:

```
docker compose start
docker compose up --detach
```

## Automated database backups

The Docker configuration package includes a mechanism that will perform periodic backups of your MySQL database, using: [databacker/mysql-backup](https://github.com/databacker/mysql-backup). It is by default configured to perform a dump every two hours. See [configuration](https://github.com/databacker/mysql-backup/blob/master/docs/configuration.md) for more options.

## Proxy Configuration

The Docker configuraiton 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](https://hub.docker.com/_/nginx) for more configuration options.