Troubleshooting

This section summarizes issues that commonly arise during setup and how to resolve them. When a problem occurs, start by finding the relevant symptom in Symptom Index and reviewing the possible causes and solutions.

Symptom Index

Symptom	Primary Cause	Reference
docker compose build fails	Missing materials / proxy / network	Missing Required Materials / Proxy-Related Issues
Container stops immediately after docker compose up -d	Port conflict / missing materials / initialization error	Port Conflicts / Cassandra/Solr Initialization Errors
Cannot connect to http://127.0.0.1/imart/system/login	httpd / resin not started / Resin not yet finished starting	Common Issues
Can access the system admin screen but cannot log in to the tenant screen	Tenant environment setup not done / Cassandra configuration mismatch	Tenant Environment Setup
war build fails	Git LFS files not retrieved / proxy	Git LFS Files Not Retrieved / Proxy-Related Issues
Emails cannot be sent / nothing arrives in mailpit	Email configuration / Resin SMTP connection failure	Emails Not Appearing in mailpit
Only one Resin connects in cluster configuration	Startup issue with one Resin node	Cluster Configuration-Specific Issues

Common Issues

Port Conflicts

If an existing service is using any of the ports required by this environment, the container will fail to start. The ports used are as follows:

• 80 (Apache HTTPd)
• 8080 (Resin / Resin1)
• 8081 (Resin2, cluster configuration only)
• 9000 (Resin / Resin1 server-side script debugging)
• 9001 (Resin2 server-side script debugging, cluster configuration only)
• 8983 (Solr)
• 9160 (Cassandra)
• 8188 (Accel Studio Testing Function Test Execution Agent)
• 8025 (mailpit)

The database port depends on the selected branch. See the README.md of the selected branch (for example, 5432 for PostgreSQL).

Either free the conflicting port or modify the port mapping in compose.yaml.

Git LFS Files Not Retrieved

If Git LFS is not installed or not initialized before cloning, files under imm/lib and juggling-build-war/lib will remain as LFS pointer files (a few hundred bytes).

git lfs install
git lfs pull

Run the commands above. If the issue persists, consider re-cloning the repository.

Proxy-Related Issues

In proxy environments, Git, Docker Desktop, and middleware inside containers may each require separate configuration.

• Git: git config --global http.proxy http://proxy:port / https.proxy http://proxy:port
• Docker Desktop: Settings > Resources > Proxies, or the proxies key in <user home>/.docker/settings.json / daemon.json
• Resin (inside container): Proxy settings in resin/overwrite/conf/resin.properties or resin.xml
  • If resin.xml is edited, rebuilding the image (docker compose build --no-cache) and recreating the container (docker compose up -d) are required.

Missing Required Materials

Check that none of the following materials are missing:

Configuration	Destination	Material
Standalone / Cluster	resin/	Resin Pro
Standalone / Cluster	cassandra/	Apache Cassandra
Standalone / Cluster	solr/	Solr installer
Standalone / Cluster	accelstudio-testing-agent/	Accel Studio Testing Function Test Execution Agent

For the exact file names of each material, refer to the README.md of the selected branch.

If you are using Oracle as the database, additional manual placement (the Oracle JDBC driver) is required beyond the above. See the README.md of the selected branch for details.

The end of the build error log will show which material's COPY or extraction failed.

Cassandra/Solr Initialization Errors

Cassandra and Solr initialize their data directories (data/cassandra and data/solr) on first startup. If data left from a previous build is incompatible with the version of a new build, a startup error may occur.

In that case, stop the containers, delete the data directories, and restart. For details, see The data/ Directory: Description and Usage.

Initialization Deletes Data

Deleting data/cassandra, data/solr, or similar directories will permanently remove any accumulated data. Back up the data before deleting if needed.

Emails Not Appearing in mailpit

If emails sent from iAP do not appear in the mailpit web UI (http://127.0.0.1:8025), check the following:

• The STATUS for mailpit in docker compose ps shows Up.
• docker compose logs mailpit shows SMTP receive logs (if not, the connection from the sender is not reaching mailpit).
• juggling-build-war/overwrite/conf/javamail-config/javamail-config.xml has host="mailpit" / port="1025" set in <smtp-server>.

If javamail-config.xml is changed, a war rebuild and Resin restart are required (→ The data/ Directory: Description and Usage - "Replacing the IM-Juggling Project").

Cluster Configuration-Specific Issues

Only One Resin Node Connects

It is possible that only resin1 or only resin2 is running. Check the STATUS of both Resin instances with docker compose ps, then examine the logs for the affected Resin with docker compose logs -f resin1 or docker compose logs -f resin2.

Uneven Request Distribution to Resin Nodes

Browser-side session persistence (sticky sessions) and similar mechanisms may cause requests to concentrate on a specific Resin instance. Clear the browser session, or access from a different browser or incognito window to verify distribution.

Inconsistencies from Shared Storage

data/resin/storage is a shared area mounted by both resin1 and resin2. When manually editing or deleting files in this area, take the state of both Resin instances into account.

Collecting Information When Issues Persist

If the issue cannot be resolved, collect the following information:

# Status of each container
docker compose ps

# Logs for each service (specify the target service based on the situation)
docker compose logs --tail=200 resin   # For standalone configuration
docker compose logs --tail=200 resin1  # For cluster configuration
docker compose logs --tail=200 resin2  # For cluster configuration
docker compose logs --tail=200 httpd
docker compose logs --tail=200 <db>    # Database (<db> is the DB service name for the selected branch, e.g., postgresql)
docker compose logs --tail=200 cassandra
docker compose logs --tail=200 solr

# Detailed container information
docker inspect <container name>

If the issue still cannot be resolved, resetting the data and rebuilding is also an option. For reset steps, see The data/ Directory: Description and Usage.