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

> Start MobileAudit locally with Docker Compose. Clone the repo, build images, and run the development setup for instant access to the security scanner dashboard at localhost:8888.

- Repository: [Mónica Pastor/mobileaudit](https://github.com/mpast/mobileaudit)
- Tags: getting-started
- Published: 2026-03-07

---

**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)](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)](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`](https://github.com/mpast/mobileaudit/blob/main/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)](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`](https://github.com/mpast/mobileaudit/blob/main/.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:

```bash
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)](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml) file automatically loads [`.env.example`](https://github.com/mpast/mobileaudit/blob/main/.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:

```bash
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`](https://github.com/mpast/mobileaudit/blob/main/Dockerfile), which installs system dependencies including OpenJDK, wkhtmltopdf, and the JADX decompiler. Build the image before starting the stack:

```bash
docker-compose build

```

### Launch the Development Stack

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

```bash
docker-compose up

```

Alternatively, run in detached mode to free your terminal:

```bash
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)](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)](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)](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)](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)](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)](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)](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)](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`](https://github.com/mpast/mobileaudit/blob/main/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`](https://github.com/mpast/mobileaudit/blob/main/docker-compose.yaml) and the upstream settings in [`nginx/app.conf`](https://github.com/mpast/mobileaudit/blob/main/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`](https://github.com/mpast/mobileaudit/blob/main/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`](https://github.com/mpast/mobileaudit/blob/main/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`](https://github.com/mpast/mobileaudit/blob/main/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`](https://github.com/mpast/mobileaudit/blob/main/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`.