Bookstack Known Issues

This section contains a list of known issues, transient bugs, and edge cases discovered during deployment and testing of BookStack via AWS Marketplace.

The purpose of this documentation is to help users understand occasional anomalies (such as cloud-init failures, DNF cache issues, or AMI-related differences) and provide guidance on how to resolve or ignore them when appropriate.
If you’re experiencing an issue during initial launch, check here before escalating.

🐞 Known Issues During First Launch (EC2 from AWS Marketplace)

This document contains a list of known issues that may occur during the initial launch of the EC2 instance when deploying BookStack via AWS Marketplace. These behaviors are considered normal and self-recovering in most cases.

⚠️ 1. Transient DNF Cache Failures

Symptoms:

• Cloud-init fails with messages like:

[Errno 2] No such file or directory: '/var/cache/dnf/.../*.rpm'
Failed to run module scripts-user
Cause:

• This issue is caused by a temporary inconsistency between metadata and actual RPM packages in Amazon Linux 2023 mirrors.

• It may also be triggered by race conditions within cloud-init (e.g., DNF downloads package, then cache becomes unavailable before install completes).

Workaround:

• The Auto Scaling Group will automatically replace the failed instance.

• On the second attempt, the packages are downloaded again and the process typically succeeds.

Recommendation:

• Add retry logic and DNF cache clearing in your user-data, such as:

dnf clean all
dnf makecache
retry dnf install -y ...

⚠️ 2. cloud-init Failure After SELinux Reboot

Symptoms:
⚠️ On Amazon Linux 2023, the system may reboot automatically on first launch to apply SELinux settings.
This may cause the initial cloud-init status to show as failed, even though the environment is ready.
Log shows:
Rebooting machine to apply SELinux kernel commandline setting
Failed to run module scripts-user
Ran 20 modules with 1 failures
Workaround:

• The system reboots automatically and continues working fine.

• No action is required — this is an expected behavior.

• Optional: Use the following EC2AMI parameter value: /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-arm64.

⚠️ 3. Duplicate Welcome Message in Shell

Symptoms:
sh-5.2$ sudo su - ec2-user
Last login: Tue Apr  8 08:03:38 UTC 2025 on pts/1
 Welcome to your EC2 instance!
-----------------------------
 Operating System: GNU/Linux
 Hostname: ip-172-31-7-183.ec2.internal
 Current Date and Time: Tue Apr  8 08:14:25 UTC 2025
-----------------------------
 Welcome to your EC2 instance!
-----------------------------
 Operating System: GNU/Linux
 Hostname: ip-172-31-7-183.ec2.internal
 Current Date and Time: Tue Apr  8 08:14:25 UTC 2025
Cause:

• The base AMI used by AWS during scanning includes pre-installed user-data scripts or messages, and this overlaps with your current user-data.

Resolution:

• Ignore — has no effect on functionality.

• Optional: Use the following EC2AMI parameter value: /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-arm64.

⚠️ 4. EC2 Instance Logs Are Not Persisted to File

Symptoms:

• File /var/log/journal/log-export.log is missing after instance launch.

Cause:

• The logging unit contains a misconfigured ExecStart command in the file: /etc/systemd/system/journald-export.service

Incorrect line:
ExecStart=/bin/bash -c "journalctl -f -o short-iso > tee -a /var/log/journal/log-export.log"
Correct line should be:
ExecStart=/bin/bash -c "journalctl -f -o short-iso > /var/log/journal/log-export.log"
Resolution:
sudo systemctl daemon-reload
sudo systemctl enable --now journald-export.service
sudo systemctl start journald-export.service

✅ Summary

These issues do not indicate a failure of the product, but are a result of how cloud-init, Amazon Linux 2023, and Marketplace validation behave. 

🔧 The duplicate welcome screen and missing EC2 instance logs are known issues and will be addressed in a future release.