phishingclub/DEVELOPMENT.md

Development

How to run Phishing Club locally. For the contribution process (branching, signed commits, pull requests) see CONTRIBUTING.md.

The development environment is also a safe, contained place to learn hands-on phishing. Spin up campaigns, test templates, and inspect traffic. It comes with containers for local SMTP/mailbox, a MITMProxy for viewing traffic towards proxied sites, and everything else you need. Need help? Join the Discord.

Prerequisites

• Docker and Docker Compose
• Git
• Make (recommended, the development workflow is built around make)
• Enough memory for the first build. The first start compiles the whole backend dependency graph and installs the frontend, which is memory heavy. On a machine with limited memory these two steps running at once can be killed by the OOM killer, showing up as signal: killed on the backend and vite: not found on the frontend. On such machines start with make up-low-mem, which builds the backend before starting the frontend so the heavy steps do not overlap. Otherwise use the normal make up, which builds everything in parallel for the fastest startup.

Quick Start

1. Clone the repository:

git clone https://github.com/phishingclub/phishingclub.git
cd phishingclub

2. Start the services:

make up

Wait for the backend to finish starting before continuing. Follow the startup with make logs.

3. Access the platform:

• Administration: https://localhost:8003
• HTTP Phishing Server: http://localhost:80
• HTTPS Phishing Server: https://localhost:443

4. Get admin credentials:

The username and password are output in the terminal when you start the services. If you restart the backend service before completing setup by logging in, the username and password will change.

make backend-password

make backend-password outputs the password from the latest setup, so you can use it instead of scrolling back through the logs.

5. Setup and start phishing:

Open https://localhost:8003 and setup the admin account using the credentials from step 4.

Visit the Phishing Club Guide for more information.

Development Services and Ports

Port	Service	Description
80	HTTP Phishing Server	HTTP phishing server for campaigns
443	HTTPS Phishing Server	HTTPS phishing server with SSL
8002	Backend API	Backend API server
8003	Frontend	Development frontend with Vite
8101	Database Viewer	DBGate database administration
8102	Mail Server	Mailpit SMTP server with SpamAssassin integration
8103	Container Logs	Dozzle log viewer
8104	Container Stats	Docker container statistics
8105	MITMProxy	MITMProxy web interface
8106	MITMProxy	MITMProxy external access
8107	API Test Server	Test endpoint for the API Sender
8201	ACME Server	Pebble ACME server for certificates
8202	ACME Management	Pebble management interface
8203	ACME Challenge	Pebble challenge test server

Development Commands

The makefile has a lot of convenience commands for development.

# Start all services
make up

# Stop all services
make down

# View logs
make logs

# Restart specific service
make backend-restart
make frontend-restart

# Access service containers
make backend-attach
make frontend-attach

# Reset backend database
make backend-db-reset

# Get backend admin password
make backend-password

Development Domains

For development we use .test for all domains.

The Docker Compose stack includes a DNSMasq container that resolves .test domains on the internal Docker network, so the containers can reach each other. This does not cover your host. You must ALSO handle resolution on your own machine, either by adding the .test domains you use to your hosts file or by running a local DNS server that resolves all *.test domains to 127.0.0.1.

Option 1: DNSMasq (Recommended)

# Add to your DNSMasq configuration
address=/.test/127.0.0.1

Option 2: Hosts File

Add to /etc/hosts:

127.0.0.1 microsoft.test
127.0.0.1 google.test
... add your development domains here

Development SSL Certificates

The development environment uses Pebble ACME server for automatic SSL certificate generation. In production, configure your preferred ACME provider or upload custom certificates.

If you experience any issues with certificate generation, bring the backend down, clear the local certs and start the backend again:

• make backend-down
• make backend-clear-certs
• make backend-up

Certificate warning

When developing it can be nice to ignore certificate warnings, especially when handling complex proxy setups. Use a dedicated browser and skip certificate warning.

On Ubuntu you can add custom shortcut for chromium without cert warnings.

~/.local/share/applications/chromium-dev.desktop

[Desktop Entry]
Version=1.0
Type=Application
Name=Chromium Phishing Dev
Comment=Chromium for development with SSL certificate errors ignored
Exec=chromium-browser --ignore-certificate-errors --incognito
Icon=chromium-browser
Terminal=false