This is the installation guide for Posda.
Things to consider
There are a handful of things you should consider before beginning installation, such as:
- What host OS will you use?
- What type of installation?
- Will storage be separate?
- Will database be separate?
Host OS
Posda is distributed as a set of Docker containers, which means that it will technically work on any platform Docker supports (including Windows, MacOS, and Linux). However, we recommend Linux be used for the best compatibility. MacOS is the second-best choice, and we discourage the use of Windows.
Any Linux distribution should work, as long as you can install Docker, though we have tested Posda on the following:
- Ubuntu 16.04, 18.04
- RHEL 7
- Alpine
Type of Installation
Posda supports a number of different types of installation. The main options are if separate storage will be used, and/or a separate database server. The reasons why you would make these choices are beyond the scope of this documentation, but you should make those choices before beginning installation.
We have included three example configurations in this guide:
- Small - Single machine, for a small site, or development, or demonstration
- Medium - When separate storage is needed
- Large - When separate storage and database servers are needed
Install Sizes / Types
Here are three common types of installations, along with a list of which sections you would need to follow for each.
Small / Development Installation
This is the appropriate set of sections you would follow to install Posda on a single machine, such as for development or demonstration purposes, or just an environment where this is all that is required.
Medium / Separate Storage
- Install Docker
- Clone the Repo
- Connect storage to Host
- Configure storage in docker-compose.yaml
- Configure Common Settings
- Start Posda
Large / Separate Storage and Separate Database
- Provision database server, install PostgreSQL
- Install Docker
- Clone the Repo
- Connect storage to Host
- Configure storage in docker-compose.yaml
- Configure database
- Configure Common Settings
- Start Posda
Install Docker
Installing Docker is beyond the scope of this documentation. You can find further information at the Docker Homepage.
Make sure you also install docker-compose
. Instructions are available at
Install Docker Compose.
Clone Oneposda
First you will need to install git
on your system. Once you have git,
simply clone Posda by typing:
git clone https://code.imphub.org/scm/pt/oneposda.git
You can place this directory anywhere you like.
Configure Storage
The bulk of the storage will be from the "Posda Cache", where all imported and edited DICOM files are stored. There is also the Postgres database data, if you are using the built-in database.
By default both storage locations are managed by Docker, but you may want to configure the location yourself, such as on network attached storage.
The main way you do this is by changing the volume
sections within the
various services in the docker-compose.yaml
file.
For example, if you wanted to place all of the cache (DICOM) files within
the host directory /mnt/storage/posda
, you would find all lines within
docker-compose.yaml
that look like:
- posda_cache_alpine:/home/posda/cache
and change them to:
- /mnt/storage/posda:/home/posda/cache
Make sure you change all occurrences!
NOTE: You should ensure that the owner:group ID of the chosen location
is 2123:2123
.
If you additionally wanted to change where the built-in Postgres database
stores its data, first choose a location (such as /mnt/storage/database
),
then change the line that looks like:
- pgdata_alpine:/var/lib/postgresql/data
to instead be:
- /mnt/storage/database:/var/lib/postgresql/data
Configure Database
If you have chosen to use a separate database host (instead of using the container), you will need to complete this section.
First, you must remove the db
service from the docker-compose.yaml
file.
Remove these lines:
db:
image: postgres:10.1-alpine
restart: always
environment:
POSTGRES_PASSWORD: example
volumes:
- pgdata_alpine:/var/lib/postgresql/data
ports:
- 5433:5432
Then, find every occurrence of depends_on: db
and remove it. For example,
remove only the - db
line from the following:
depends_on:
- db
- redis
Remove this everywhere it occurs, otherwise the various containers will fail to start.
Finally, you must edit the database.env
file, and set the appropriate values
for the database server you have configured. You must use a role which has
the ability to create databases. After initial configuration you can remove
that right, if you want.
Example:
PGHOST=my-database-host.uams.edu
PGUSER=posda
PGPASSWORD=s3cret!
Configure Common Settings
Edit the file common.env
and set the values. In particular, you should
carefully choose POSDA_EXTERNAL_HOSTNAME
.
Start Posda
The first time you start Posda, you will want to start the db
and posda
containers first, and wait about 30 seconds after each command for
initial setup to complete.
The manage
script is a simple wrapper around docker-compose
, but it
configures some things before each run, so it is recommend you use it
rather than using docker-compose
directly.
WARNING: If you have chosen to have a separate database host, you must skip the first command.
From the oneposda
directory, execute:
./manage up -d db
# Wait 30 seconds for the database to start
./manage up -d posda
# Wait 30 seconds for initial setup to complete
./manage up -d