Skip to content

Commit 5ab045a

Browse files
derkaiserreichderkaiserreich
committed
Enhancement: Simplify Docker setup, remove Swarm mode, and apply compose best practices
1 parent 04a55a3 commit 5ab045a

File tree

3 files changed

+217
-98
lines changed

3 files changed

+217
-98
lines changed

‎README.md‎

Lines changed: 144 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,170 @@
1+
# Structr Docker Setup
2+
13
[![Tests](https://github.com/structr/docker-setup/actions/workflows/main.yml/badge.svg)](https://github.com/structr/docker-setup/actions/workflows/main.yml)
24

3-
# Structr Docker Setup
5+
A Docker Compose setup for running Structr with a pre-configured Neo4j database.
6+
7+
---
8+
9+
## Requirements
10+
11+
- Docker
12+
- Docker Compose
13+
14+
---
15+
16+
## Quick Start (Easiest Method)
17+
18+
This is the simplest way to get started. No configuration needed.
19+
20+
1. **Start the containers:**
21+
```bash
22+
docker compose up -d
23+
```
24+
25+
2. **Access Structr:**
26+
Open http://127.0.0.1:8082/structr/ in your browser
27+
28+
3. **Stop the containers:**
29+
```bash
30+
docker compose down
31+
```
32+
33+
**Note:** This uses Docker-managed volumes. Your data persists between restarts but is managed internally by Docker.
34+
35+
---
36+
37+
## Advanced Setup (Custom Volume Directories)
38+
39+
If you want to access Structr data directly on your host filesystem (useful for deployments and backups), you can use custom volume mounts.
40+
41+
### Initial Setup
42+
43+
1. **Run the setup script:**
44+
```bash
45+
./setup.sh
46+
```
47+
This creates local directories and sets proper permissions.
48+
49+
2. **Add your license file:**
50+
- If you have a Structr license, copy it to `./structr/license.key`
51+
- For community edition, the setup script creates an empty file for you
52+
53+
3. **Modify docker-compose.yml:**
54+
55+
Replace the named volumes with bind mounts. Change the `volumes` section for each service:
56+
57+
**For Neo4j:**
58+
```yaml
59+
volumes:
60+
- ./volumes/neo4j-database:/data
61+
- ./volumes/neo4j-logs:/logs
62+
```
63+
64+
**For Structr:**
65+
```yaml
66+
volumes:
67+
- ./volumes/structr-files:/var/lib/structr/files
68+
- ./volumes/structr-repository:/var/lib/structr/repository
69+
- ./volumes/structr-logs:/var/lib/structr/logs
70+
- ./structr/license.key:/var/lib/structr/license.key
71+
```
72+
73+
4. **Start the containers:**
74+
```bash
75+
docker compose up -d
76+
```
77+
78+
### Benefits of Custom Volume Directories
79+
80+
- Direct access to logs in `./volumes/structr-logs/` and `./volumes/neo4j-logs/`
81+
- Easy backup and restore of data
82+
- Simplified deployment workflows (see below)
83+
84+
---
85+
86+
## Working with Containers
87+
88+
### View running containers
89+
```bash
90+
docker ps
91+
```
92+
93+
### Access container shell
94+
```bash
95+
docker exec -it <container_id> /bin/sh
96+
```
497

5-
### Requirements:
6-
- docker
7-
- (docker-compose)
98+
### View logs
99+
```bash
100+
docker compose logs # All logs
101+
docker compose logs structr # Structr logs only
102+
docker compose logs neo4j # Neo4j logs only
103+
```
8104

9-
----
105+
---
10106

11-
### First steps:
107+
## Deployment Workflow
12108

109+
When using custom volume directories, you can deploy Structr applications through the repository directory.
13110

14-
- Make sure, you have a valid Structr license.key file and copy it to ./structr/license.key. If you want to run the community edition of Structr, you can create an empty file and move it also to ./structr/license.key.
111+
**Important: Follow this order:**
15112

16-
### Usage with docker-compose:
17-
##### Initial setup:
113+
1. Clone your application repository to `./volumes/structr-repository`
18114

19-
- Run the setup.sh script before starting the stack, so all necessary volume folders for mounting to the containers are created. (Only for Unix and macOS users)
20-
- Copy your license.key file to ./structr/license.key
21-
- Run `docker-compose build`
115+
2. Navigate to Structr's dashboard at http://localhost:8082/structr/#dashboard → Deployment
22116

23-
##### Starting the instances:
24-
- Run `docker-compose --compatibility up -d` to start Neo4j and Structr
25-
- Open `http://127.0.0.1:8082/structr/` in your browser to access Structr
117+
3. **Import application:**
118+
- Enter `/var/lib/structr/repository/webapp` in the "Application import from server directory" field
119+
- Click import
26120

27-
##### Stopping the instances:
28-
- `docker-compose down`
121+
4. **Export changes:**
122+
- After making changes in Structr
123+
- Enter `/var/lib/structr/repository/webapp` in the "Application export to server directory" field
124+
- Click export
29125

30-
##### Inspecting the containers
31-
- `docker ps`
32-
- `note the container id`
33-
- `docker exec -it <Unique identifier for container> /bin/sh`
126+
5. **Commit and push:**
127+
- From the host system, commit your changes in `./volumes/structr-repository`
128+
- Push to your repository
34129

35-
##### Inpecting the service log files
36-
- `docker-compose logs` will print out the server.log of structr and the neo4j.log of Neo4j
37-
- The Structr container server.log will also be written to ./volumes/structr-logs/server.log, the Neo4j debug.log and neo4j.log will be written to ./volumes/neo4j-logs/*.log
130+
6. **Deploy updates:**
131+
- Pull the latest changes
132+
- Repeat from step 3
38133

39-
----
134+
---
40135

41-
### Usage with docker swarm:
42-
##### Initial setup:
136+
## Configuration
43137

44-
- Run the setup.sh script before starting the stack, so all necessary volume folders for mounting to the containers are created. (Only for Unix and macOS users)
45-
- copy your license.key file to ./structr/license.key
46-
- run `docker swarm init`
138+
### Default Credentials
47139

48-
##### Starting the instances:
49-
- Run `docker stack deploy --compose-file docker-compose.yml structr` to start Neo4j and Structr
50-
- Open `http://127.0.0.1:8082/structr/` in your browser to access Structr
140+
- **Structr:**
141+
- Username: `admin`
142+
- Password: `admin`
51143

52-
##### Stopping the instances:
53-
- `docker stack rm structr`
144+
- **Neo4j:**
145+
- Username: `neo4j`
146+
- Password: `structrDockerSetup`
54147

55-
##### Inspecting the containers
56-
- `docker ps`
57-
- `note the container id`
58-
- `docker exec -it <Unique identifier for container> /bin/sh`
148+
### Resource Limits
59149

60-
##### Inspecting the stack
61-
- Run `docker stack ps structr` to get a list of all tasks in the structr stack
62-
- Run `docker stack services structr` to get a list of all services in the structr stack
150+
You can adjust CPU and memory limits in `docker-compose.yml` under the `deploy.resources` section for each service.
63151

64-
##### Inpecting the service log files
65-
- The Structr container server.log will be written to ./volumes/structr-logs/server.log, the Neo4j debug.log and neo4j.log will be written to ./volumes/neo4j-logs/*.log
152+
Default limits:
153+
- **CPU:** 2 cores limit, 1 core reserved
154+
- **Memory:** 4GB limit, 1GB reserved
66155

67-
----
156+
---
68157

69-
### Customizing Ressources
70-
The CPU and RAM configuration of the containers can be changed in the docker-compose.yml file.
158+
## Troubleshooting
71159

72-
----
160+
### Containers won't start
161+
- Check if ports 8082, 7474, 7473, or 7687 are already in use
162+
- View logs with `docker compose logs`
73163

74-
### Deployment Roundtrip of an Structr application (order is crucial!!!):
164+
### Permission issues with custom volumes
165+
- Run the setup script again: `./setup.sh`
166+
- Ensure your user is in the `structr` group (may require logout/login)
75167

76-
1. clone repository to ./volumes/structr-repository
77-
2. goto `http://localhost:8082/structr/#dashboard` -> Deployment
78-
3. copy `/var/lib/structr/repository/webapp` into the 'Application import from server directory' input field and click on the import button
79-
4. when changes have been made copy the same path into the 'Application export to server directory' input field and click the button
80-
5. commit your changes on the host system to github
81-
6. pull the new repository version
82-
7. push your changes
83-
8. repeat from 3.
168+
### Data persistence
169+
- **Quick Start method:** Data stored in Docker volumes, persists until you run `docker compose down -v`
170+
- **Advanced method:** Data stored in `./volumes/` directory on your host

‎docker-compose.yml‎

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,21 @@ version: '3.3'
22
services:
33
neo4j:
44
image: neo4j:latest
5+
container_name: structr-neo4j
6+
restart: unless-stopped
57

6-
# Structr versions < 4.0 can't change the initial neo4j password, so it has to be
7-
# set in the environment of the docker container. The password here has to be the
8-
# same as in the structr.conf file (default-migrated.database.connection.password).
98
environment:
109
- NEO4J_AUTH=neo4j/structrDockerSetup
10+
- NEO4J_server_memory_heap_initial__size=1G
11+
- NEO4J_server_memory_heap_max__size=2G
12+
- NEO4J_server_memory_pagecache_size=1G
1113

12-
# Uncomment to give host access to the service container
14+
# Uncomment to access Neo4j browser and Bolt from host
1315
# ports:
14-
# - "7474:7474"
15-
# - "7473:7473"
16-
# - "7687:7687"
16+
# - "7474:7474" # HTTP
17+
# - "7473:7473" # HTTPS
18+
# - "7687:7687" # Bolt
1719

18-
# For swarm mode deployment only.
1920
deploy:
2021
resources:
2122
limits:
@@ -33,34 +34,44 @@ services:
3334

3435
# Put service networks so Structr and Neo4j can communicate
3536
networks:
36-
database:
37+
structr-network:
3738
aliases:
3839
- neo4j
3940
structr:
4041
image: structr/structr:5.2.1
42+
container_name: structr-app
43+
restart: unless-stopped
4144
depends_on:
4245
- neo4j
4346
ports:
4447
- "8082:8082"
4548
environment:
49+
# JVM Memory Settings
4650
- STRUCTR_MIN_HEAP=1g
4751
- STRUCTR_MAX_HEAP=4g
52+
53+
# Privacy Policy Agreement
4854
- AGREE_TO_STRUCTR_PRIVACY_POLICY=yes
55+
56+
# Superuser Configuration
4957
- STRUCTR_superuser_password=superuser
58+
59+
# Neo4j Connection Configuration
5060
- STRUCTR_database_available_connections=neo4j_default
5161
- STRUCTR_neo4j__default_database_driver=org.structr.bolt.BoltDatabaseService
5262
- STRUCTR_neo4j__default_database_connection_name=neo4j_default
5363
- STRUCTR_neo4j__default_database_connection_url=bolt://neo4j:7687
5464
- STRUCTR_neo4j__default_database_connection_username=neo4j
5565
- STRUCTR_neo4j__default_database_connection_password=structrDockerSetup
5666
- STRUCTR_nodeservice_active=neo4j_default
67+
68+
# Schema Configuration
5769
- STRUCTR_application_schema_automigration=true
58-
59-
# Add file system group for repository directory mount
70+
71+
# Deployment Configuration (for repository directory mount)
6072
- STRUCTR_deploymentservlet_filegroup_name=structr
6173
- STRUCTR_deploymentservlet_filegroup_id=8082
6274

63-
# For swarm mode deployment only.
6475
deploy:
6576
resources:
6677
limits:
@@ -70,25 +81,27 @@ services:
7081
cpus: '1'
7182
memory: 1g
7283

73-
# Add volumes for data retention
7484
volumes:
75-
76-
# folders
7785
- structr-files:/var/lib/structr/files
7886
- structr-repository:/var/lib/structr/repository
7987
- structr-logs:/var/lib/structr/logs
8088
- ./structr/license.key:/var/lib/structr/license.key
8189

8290
# Put service into network so Structr and Neo4j can communicate
8391
networks:
84-
database:
92+
structr-network:
8593

8694
volumes:
95+
neo4j-database:
96+
name: structr-neo4j-database
97+
neo4j-logs:
98+
name: structr-neo4j-logs
8799
structr-files:
100+
name: structr-files
88101
structr-repository:
102+
name: structr-repository
89103
structr-logs:
90-
neo4j-database:
91-
neo4j-logs:
104+
name: structr-logs
92105

93106
networks:
94-
database:
107+
structr-network:

0 commit comments

Comments
 (0)