How to Start MobileAudit Locally Using Docker Compose: Complete Development Setup Guide

To start MobileAudit locally using Docker Compose, clone the mpast/mobileaudit repository, run docker-compose build to compile the Django and Celery images, then execute docker-compose up and navigate to http://localhost:8888/ to access the security scanner dashboard.

MobileAudit is an open-source Django-based web application for automated mobile application security analysis. This guide explains exactly how to start MobileAudit locally using Docker Compose with the development configuration, covering the multi-service architecture defined in [docker-compose.yaml](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml) that orchestrates PostgreSQL, RabbitMQ, Nginx, and Celery workers.

Understanding the MobileAudit Development Architecture

Before launching the stack, it is important to understand the five interconnected services defined in the development [docker-compose.yaml](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml):

• db: PostgreSQL database (port 5432 internally) that persists scan results and application metadata in the named volume db-data.
• web: The Django application server running Gunicorn on port 8000, built from the repository's Dockerfile.
• nginx: Reverse proxy that exposes the application on host port 8888 and forwards traffic to the web service (configured in [nginx/app.conf](https://github.com/mpast/mobileaudit/blob/main/nginx/app.conf)).
• rabbitmq: Message broker (port 5672) that queues background tasks for the Celery worker.
• worker: Celery worker instance that executes long-running mobile application scans, sharing the same Docker image as the web service.

All services load environment variables from .env.example, which provides sensible defaults for local development, including database credentials and the CELERY_BROKER_URL.

Step-by-Step Guide to Start MobileAudit Locally Using Docker Compose

Follow these sequential steps to launch the complete development environment on your local machine.

Clone the Repository

First, download the source code and navigate into the project directory:

git clone https://github.com/mpast/mobileaudit.git
cd mobileaudit

Configure Environment Variables

The [docker-compose.yaml](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml) file automatically loads .env.example. However, if you need to override settings such as the Django SECRET_KEY or database password, copy the example file to .env and modify it:

cp .env.example .env

# Edit .env to override any default values

Build the Docker Images

The web and worker services share a single image defined in the Dockerfile, which installs system dependencies including OpenJDK, wkhtmltopdf, and the JADX decompiler. Build the image before starting the stack:

docker-compose build

Launch the Development Stack

Start all services in the foreground to observe logs during initialization:

docker-compose up

Alternatively, run in detached mode to free your terminal:

docker-compose up -d

During startup, the web service executes [entrypoint/web_entrypoint.sh](https://github.com/mpast/mobileaudit/blob/main/entrypoint/web_entrypoint.sh), which performs Django migrations, collects static files, and launches Gunicorn. Simultaneously, the worker service runs [entrypoint/worker_entrypoint.sh](https://github.com/mpast/mobileaudit/blob/main/entrypoint/worker_entrypoint.sh) to start the Celery worker process.

Verify the Installation

Once the containers report healthy status, open your browser and navigate to:

http://localhost:8888/

The Nginx reverse proxy (configured in [nginx/app.conf](https://github.com/mpast/mobileaudit/blob/main/nginx/app.conf)) forwards traffic to the Django application. You can log in using credentials created during migrations or register a new account through the UI.

Deep Dive into the Docker Compose Configuration

Understanding the internal architecture helps troubleshoot issues and customize the deployment.

Service Orchestration and Networking

The [docker-compose.yaml](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml) defines a default bridge network enabling DNS resolution between containers. The web service (port 8000) is not exposed directly to the host; instead, the nginx service maps host port 8888 to the container's port 80, then proxies to web:8000 via the upstream configuration in [nginx/app.conf](https://github.com/mpast/mobileaudit/blob/main/nginx/app.conf).

Entrypoint Automation

Container initialization relies on shell scripts to ensure database readiness and static asset collection:

• Web Entrypoint: [entrypoint/web_entrypoint.sh](https://github.com/mpast/mobileaudit/blob/main/entrypoint/web_entrypoint.sh) executes python manage.py migrate, python manage.py collectstatic --noinput, and finally starts gunicorn app.wsgi:application --bind 0.0.0.0:8000.
• Worker Entrypoint: [entrypoint/worker_entrypoint.sh](https://github.com/mpast/mobileaudit/blob/main/entrypoint/worker_entrypoint.sh) launches the Celery worker with celery -A app.worker.celery worker --loglevel=info.

Data Persistence Strategy

The PostgreSQL service uses a named Docker volume db-data (defined in [docker-compose.yaml](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml)) to persist database files across container restarts. This ensures scan results and user data survive docker-compose down operations. For live development, the project root is bind-mounted into the web and worker containers (- .:/app), enabling immediate reflection of code changes without image rebuilds.

Summary

• Clone the mpast/mobileaudit repository and enter the project directory.
• Configure environment variables by optionally copying .env.example to .env for custom overrides.
• Build the Docker image using docker-compose build to compile dependencies including OpenJDK and JADX.
• Launch the full stack with docker-compose up, which starts PostgreSQL, RabbitMQ, Django (via Gunicorn), Celery workers, and Nginx.
• Access the application at http://localhost:8888/ via the Nginx reverse proxy configured in nginx/app.conf.
• Persist data using the named Docker volume db-data, ensuring scan results survive container restarts.

Frequently Asked Questions

What is the default port for accessing MobileAudit in development mode?

The Nginx reverse proxy exposes the application on port 8888 by default. When you run docker-compose up, navigate to http://localhost:8888/ to access the dashboard. This mapping is defined in the nginx service configuration within docker-compose.yaml and the upstream settings in nginx/app.conf.

Do I need to create a .env file before running docker-compose?

No, creating a .env file is optional. The docker-compose.yaml file explicitly loads environment variables from .env.example, which contains sensible defaults for local development. However, if you need to override settings like the Django SECRET_KEY or database credentials, copy .env.example to .env and modify the values before building the images.

How do the web and worker services share code changes without rebuilding?

Both services mount the project root as a bind volume (- .:/app in docker-compose.yaml). This means any changes you make to the source code on your host machine are immediately reflected inside the running containers. Only changes to system dependencies (in Dockerfile) or Python requirements (in requirements.txt) require a rebuild using docker-compose build.

What happens to my scan data when I run docker-compose down?

Scan data persists because the PostgreSQL service uses a named Docker volume called db-data (defined in docker-compose.yaml). When you execute docker-compose down, the containers and network are removed, but the volume remains intact. Your scan results and user accounts will be available the next time you run docker-compose up. To completely remove all data, you must explicitly delete the volume using docker-compose down -v.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}