Installing an app from outside the store#

What you need

Time: 15 minutes to read before you use it

• You are signed in to the dashboard.
• Somebody at the masjid who can read a docker-compose file.

OpenMasjidOS can run software that is not in the App Store. It is turned off by default, on purpose.

Step 1 — Turn it on#

The two ways in#

Community apps. You add the address of an app store that follows the CasaOS format, then install from it. These apps arrive tagged Community.

Docker Compose. You paste a docker-compose.yml file, with an optional .env. These arrive tagged Custom.

What OpenMasjidOS checks before it runs anything#

It reads the file first and looks for settings that would give the app more of your machine than an app needs. There are two kinds of finding, and the difference is the important part of this page.

Warnings you can accept#

These are things that are sometimes legitimate and sometimes a disaster. OpenMasjidOS explains each one and asks you to confirm that you understand the risk.

Examples of what it reports:

• the app runs in privileged mode, which is full access to the machine
• the app mounts the Docker socket, which grants control of every container on the machine
• the app mounts the whole host filesystem, or a sensitive host path
• the app uses host networking, or shares the host process space
• the app builds its own image instead of using a pinned, pre-built one
• the app reads an env file outside its own folder, which could expose another app's secrets
• the file uses include or extends, which pull in settings OpenMasjidOS cannot check

Refusals you cannot accept#

Two findings have no confirmation button, and no way past. OpenMasjidOS will not run the file.

• the file attaches a volume to another OpenMasjid app's data
• the file joins another OpenMasjid app's private network

Step 2 — Paste a compose file#

Before you install anything from outside#

Ask these four questions. If you cannot answer all four, do not install it.

Question	Why it matters
Who wrote this, and would I recognise the name in a year?	An abandoned app is a hole nobody is closing.
Is the image pinned to a version?	An image tagged latest can change under you without warning.
Does it need the Docker socket or the host filesystem?	Almost nothing legitimately does.
Do I have a current backup?	So a mistake costs an evening rather than the donor records.

Checkpoint

You can explain the difference between a warning you can accept and a refusal you cannot. You have a backup from today.

If something goes wrong

What you see	Why	What to do
The 3rd Party App button is not there.	Allow custom apps is off.	Settings, then Advanced, then turn on Allow custom apps.
It says the volume attaches to another app’s data, with no way to continue.	That is a refusal, not a warning.	Nothing to override. Edit the file to use its own named volume, or do not install it.
The app installs and then stops immediately.	It is missing a setting it needs, often in the .env.	Open App options, then View logs, and read the last lines.
The port is already in use.	Another app already publishes that port.	Change the first number of the ports line in the file, then install it again.