Skip to content

Commit 7ca795f

Browse files
joecoralljoecorall
committed
Add README
1 parent 823b536 commit 7ca795f

2 files changed

Lines changed: 161 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Open Journal Systems (OJS) Docker Container
2+
3+
Dockerized deployment of [Open Journal Systems](https://pkp.sfu.ca/software/ojs/) based on the [Islandora Buildkit](https://github.com/Islandora-Devops/isle-buildkit) nginx base image.
4+
5+
## Quick Start
6+
7+
1. Generate secrets:
8+
```bash
9+
docker compose up init
10+
```
11+
12+
2. Start the containers:
13+
```bash
14+
docker compose up -d
15+
```
16+
17+
3. Access OJS at http://localhost
18+
19+
The installation will run automatically on first startup. The default admin credentials are:
20+
- Username: `admin` (configurable via `OJS_ADMIN_USERNAME`)
21+
- Password: Contents of `./secrets/OJS_ADMIN_PASSWORD`
22+
- Email: `admin@example.com` (configurable via `OJS_ADMIN_EMAIL`)
23+
24+
## Configuration
25+
26+
### OJS Configuration
27+
28+
| Environment Variable | Default | Source | Description |
29+
| :------------------- | :------ | :----- | :---------- |
30+
| OJS_DB_HOST | mariadb | environment | MariaDB/MySQL hostname |
31+
| OJS_DB_PORT | 3306 | environment | MariaDB/MySQL port |
32+
| OJS_DB_NAME | ojs | environment | Database name |
33+
| OJS_DB_USER | ojs | environment | Database user |
34+
| OJS_DB_PASSWORD | (generated) | secret | Database password (stored in `./secrets/OJS_DB_PASSWORD`) |
35+
| OJS_SALT | (generated) | secret | Salt for password hashing (stored in `./secrets/OJS_SALT`) |
36+
| OJS_API_KEY_SECRET | (generated) | secret | Secret for API key encoding (stored in `./secrets/OJS_API_KEY_SECRET`) |
37+
| OJS_ADMIN_USERNAME | admin | environment | Initial admin username |
38+
| OJS_ADMIN_EMAIL | admin@example.com | environment | Initial admin email |
39+
| OJS_ADMIN_PASSWORD | (generated) | secret | Initial admin password (stored in `./secrets/OJS_ADMIN_PASSWORD`) |
40+
| OJS_LOCALE | en | environment | Primary locale/language |
41+
| OJS_TIMEZONE | UTC | environment | System timezone |
42+
| OJS_FILES_DIR | /var/www/files | environment | Directory for uploaded files |
43+
| OJS_OAI_REPOSITORY_ID | ojs.localhost | environment | OAI-PMH repository identifier |
44+
| OJS_ENABLE_BEACON | 1 | environment | Enable PKP usage statistics beacon (1=enabled, 0=disabled) |
45+
46+
### Nginx and PHP Settings
47+
48+
See https://github.com/Islandora-Devops/isle-buildkit/tree/main/nginx#nginx-settings
49+
50+
## Secrets Management
51+
52+
Secrets are stored in the `./secrets/` directory and mounted into the container at runtime. The `generate-secrets.sh` script creates secure random values for:
53+
54+
- `DB_ROOT_PASSWORD` - MariaDB root password
55+
- `OJS_DB_PASSWORD` - OJS database user password
56+
- `OJS_ADMIN_PASSWORD` - OJS admin user password
57+
- `OJS_API_KEY_SECRET` - Secret for API key encoding/decoding
58+
- `OJS_SALT` - Salt for password hashing
59+
60+
## Customization
61+
62+
You can customize the installation by:
63+
64+
1. Setting environment variables in `docker-compose.yaml`
65+
2. Overriding default values in the Dockerfile
66+
3. Adding custom plugins to `rootfs/var/www/ojs/plugins/`
67+
68+
### Adding Plugins
69+
70+
Place plugin directories in the appropriate subdirectory under `rootfs/var/www/ojs/plugins/`:
71+
72+
- `blocks/` - Block plugins
73+
- `gateways/` - Gateway plugins
74+
- `generic/` - Generic plugins
75+
- `importexport/` - Import/export plugins
76+
- `metadata/` - Metadata plugins
77+
- `oaiMetadataFormats/` - OAI metadata format plugins
78+
- `paymethod/` - Payment method plugins
79+
- `pubIds/` - Public identifier plugins
80+
- `reports/` - Report plugins
81+
- `themes/` - Theme plugins
82+
83+
Plugins with `composer.json` files will automatically have their dependencies installed during the build.
84+
85+
## Volumes
86+
87+
The following volumes are created for data persistence:
88+
89+
- `mariadb-data` - MariaDB database files
90+
- `ojs-cache` - OJS cache files
91+
- `ojs-files` - Uploaded files (submissions, etc.)
92+
- `ojs-public` - Public files
93+
94+
## Updating OJS Version
95+
96+
To update the OJS version, modify the `OJS_VERSION` build argument in the Dockerfile:
97+
98+
```dockerfile
99+
ARG OJS_VERSION=3_5_0-1
100+
```
101+
102+
Version tags follow the format used in the [PKP OJS repository](https://github.com/pkp/ojs/tags).
103+
104+
## Troubleshooting
105+
106+
### Installation Logs
107+
108+
If the automatic installation fails, check the container logs:
109+
110+
```bash
111+
docker compose logs ojs
112+
```
113+
114+
### Database Connection Issues
115+
116+
Ensure the MariaDB container is healthy before the OJS container starts:
117+
118+
```bash
119+
docker compose ps
120+
```
121+
122+
### Resetting Installation
123+
124+
To completely reset and reinstall:
125+
126+
```bash
127+
docker compose down -v
128+
./scripts/generate-secrets.sh
129+
docker compose up -d
130+
```
131+
132+
## License
133+
134+
This Docker implementation is provided as-is. Open Journal Systems is licensed under the GNU General Public License v3. See the [OJS repository](https://github.com/pkp/ojs) for details.

‎docker-compose.yaml‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,29 +14,55 @@ secrets:
1414
file: ./secrets/OJS_API_KEY_SECRET
1515
OJS_SALT:
1616
file: ./secrets/OJS_SALT
17+
OJS_ADMIN_PASSWORD:
18+
file: ./secrets/OJS_ADMIN_PASSWORD
19+
1720
services:
21+
init:
22+
image: islandora/base:6.0.1@sha256:34c281449a339dbce75f784da7dca237a3325022868d89ab5cf6d6d8e0ca24a1
23+
restart: no
24+
volumes:
25+
- ./secrets:/secrets:rw
26+
- ./scripts:/scripts:ro
27+
- ./docker-compose.yaml:/docker-compose.yaml:ro
28+
command: /scripts/generate-secrets.sh
1829
ojs:
1930
image: ghcr.io/libops/ojs:main
2031
build: .
2132
ports:
2233
- 80:80
2334
environment:
2435
OJS_DB_HOST: mariadb
36+
OJS_DB_NAME: ojs
2537
OJS_DB_USER: ojs
38+
OJS_ADMIN_USERNAME: admin
39+
OJS_ADMIN_EMAIL: admin@example.com
40+
OJS_LOCALE: en
41+
OJS_TIMEZONE: UTC
42+
OJS_FILES_DIR: /var/www/files
43+
OJS_OAI_REPOSITORY_ID: ojs.localhost
44+
OJS_ENABLE_BEACON: 1
2645
secrets:
2746
- source: DB_ROOT_PASSWORD
2847
- source: OJS_API_KEY_SECRET
2948
- source: OJS_DB_PASSWORD
3049
- source: OJS_SALT
50+
- source: OJS_ADMIN_PASSWORD
3151
volumes:
3252
- ojs-cache:/var/www/ojs/cache:rw
3353
- ojs-files:/var/www/files:rw
3454
- ojs-public:/var/www/ojs/public:rw
3555
depends_on:
36-
- mariadb
56+
init:
57+
condition: service_completed_successfully
58+
mariadb:
59+
condition: service_started
3760
mariadb:
3861
image: islandora/mariadb:6.0.1@sha256:335df4225634f14095b337847e541d65b5abfa2fe051c7e2b93fae447cac1e58
3962
volumes:
4063
- mariadb-data:/var/lib/mysql:rw
4164
secrets:
4265
- source: DB_ROOT_PASSWORD
66+
depends_on:
67+
init:
68+
condition: service_completed_successfully

0 commit comments

Comments
 (0)