Local Configuration
Now that your application is live, it's time to bring it home — so you can develop, test, and push updates with confidence.
If you don't have them already, you'll install the core dependencies (Homebrew, Python, Node, and PostgreSQL), generate local HTTPS certificates, configure your .env file, and link your local setup to your deployed project and CI/CD pipeline.
When you're done, you'll have a fully functional local workspace where you can code, commit, and deploy seamlessly to production.
Walkthrough
FEATUREDWhat We're Setting Upexpand_more
- Homebrew - Package manager for macOS and Linux
- Git Repository - Clone your project locally
- mkcert - Local HTTPS certificates for secure development
- PostgreSQL - Database server and local database
- Python 3.13 - Runtime and virtual environment
- Node.js & npm - Frontend build tools
- Environment Variables - OAuth, email, and payment credentials
- Django Superuser - Admin access to your local application
- Stripe Configuration - Test mode payment processing
Prerequisitesexpand_more
Before starting this guide, you should have:
- A deployed Otoshek project (completed the deployment process)
- Access to your GitHub repository
- Admin access to your cloud provider (Azure or GCP)
- Your Stripe account credentials (test mode)
- Terminal/command line access on your development machine
Install Homebrew
STEP 01Homebrew is the package manager used to install most tools on macOS and Linux.
Check if Homebrew is already installed
brew --version
If you see a version number, Homebrew is already installed and you can skip to the next step. If you see "command not found", follow the installation instructions below.
macOS
Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Add Homebrew to your PATH
For zsh (default on modern macOS):
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
For bash:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
eval "$(/opt/homebrew/bin/brew shellenv)"
Verify installation
brew --version
Linux
Install Homebrew on Linux (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Follow post-installation instructions
After installation, the script will provide commands to add Homebrew to your PATH. Copy and run those commands.
Windows
For Windows users, we recommend using WSL 2 with Ubuntu, then following the Linux instructions above.
What is Homebrew and why do we need it?expand_more
Homebrew is a package manager that simplifies installing and managing software on macOS and Linux. Instead of manually downloading installers and managing dependencies, Homebrew handles everything with simple commands like brew install.
We'll use it throughout this guide to install Python, PostgreSQL, Node.js, and other development tools quickly and consistently.
Set Up Git and Clone Your Private Repository
STEP 02Your repository is private. To clone it, you'll set up SSH authentication with GitHub.
Check if Git is installed
git --version
If you see a version number, Git is already installed. If not, follow the installation instructions below.
macOS
Install Git via Homebrew
brew install git
Linux
Install Git
sudo apt update && sudo apt install -y git
Windows
Download and install "Git for Windows" from the official Git website. Accept the default settings during installation.
Generate an SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"
Press Enter to accept the default location (~/.ssh/id_ed25519). Add a passphrase when prompted (optional but recommended).
What it does:
ssh-keygen→ creates a new SSH key pair (public + private keys)-t ed25519→ specifies the algorithm. Ed25519 is a modern, fast, secure type of key (better than the old RSA ones)-C "your_email@example.com"→ adds a comment label inside the public key file, usually your email so you can remember what it's for
Start SSH agent and add your key
macOS
eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
If you generated a key with a custom filename, replace id_ed25519 with your custom name (e.g., id_ed25519_customname).
Make it persistent so macOS auto-loads the key:
printf 'Host *\n AddKeysToAgent yes\n UseKeychain yes\n IdentityFile ~/.ssh/id_ed25519\n' >> ~/.ssh/config
What's going on:
printf '...' >> ~/.ssh/config→ appends the text inside the quotes to your SSH config file (~/.ssh/config). If the file doesn't exist, it creates it.- The text inside
'...'are SSH configuration rules that tell SSH to automatically add keys and use the macOS keychain. - Important: If you used a custom filename, replace
id_ed25519with your custom name in theIdentityFileline.
If --apple-use-keychain isn't available, use: ssh-add -K ~/.ssh/id_ed25519
Linux
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
printf 'Host *\n AddKeysToAgent yes\n IdentityFile ~/.ssh/id_ed25519\n' >> ~/.ssh/config
If you generated a key with a custom filename, replace id_ed25519 with your custom name in both commands.
Windows
If using Git Bash:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
If you generated a key with a custom filename, replace id_ed25519 with your custom name.
If using the OpenSSH agent service, enable it in Services and add the key with ssh-add.
Copy your public key
macOS
pbcopy < ~/.ssh/id_ed25519.pub
Linux
xclip -sel clip < ~/.ssh/id_ed25519.pub
Or simply: cat ~/.ssh/id_ed25519.pub and copy manually
Windows
clip < ~/.ssh/id_ed25519.pub
Add SSH key to GitHub
- Log in to GitHub and click your profile picture in the top-right corner
- Select Settings
- In the sidebar under "Access", click SSH and GPG keys
- Click the New SSH key button
- Give it a descriptive title (e.g., "MacBook Pro")
- Paste your public key in the "Key" field
- Click Add SSH key
Test the connection
ssh -T git@github.com
You should see: Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.
Clone your private repository
git clone git@github.com:YOUR_USERNAME/YOUR_REPO_NAME.git
Replace YOUR_USERNAME and YOUR_REPO_NAME with your actual GitHub username and repository name.
Understanding the repository structureexpand_more
Your repository contains:
- backend/ - Django application, models, views, and API endpoints
- backend/frontend/ - React application with Vite build system
- .github/workflows/ - CI/CD pipeline configuration
- requirements.txt - Python dependencies
- manage.py - Django management commands
Install mkcert (for local HTTPS)
STEP 03mkcert lets you generate trusted HTTPS certificates for localhost.
Check if mkcert is already installed
mkcert -version
If you see a version number, mkcert is already installed and you can skip to setting up the certificates. If you see "command not found", follow the installation instructions below.
macOS
Install mkcert (if not already installed)
brew install mkcert
Install NSS (optional, for Firefox)
brew install nss
Linux
Install dependencies
sudo apt install libnss3-tools
Download and install mkcert
curl -JLO https://github.com/FiloSottile/mkcert/releases/latest/download/mkcert-$(uname -s)-$(uname -m)
chmod +x mkcert-*
sudo mv mkcert-* /usr/local/bin/mkcert
Windows
Download mkcert.exe from the GitHub releases page and add it to your PATH.
Install local certificate authority
mkcert -install
This installs the local CA in your system trust store, allowing your browser to trust locally-generated certificates.
Generate certificates for localhost
mkdir -p ~/certs
cd ~/certs
mkcert localhost 127.0.0.1 ::1
This creates SSL certificates in ~/certs/ that your local servers will use for HTTPS.
Verify and get the certificate paths
ls
realpath localhost+2.pem
realpath localhost+2-key.pem
Example output:
/Users/miniface/certs/localhost+2.pem
/Users/miniface/certs/localhost+2-key.pem
Save these paths — you'll need them to configure your backend server for HTTPS in the next step.
Configure VS Code Django debugger with SSL certificates
Open .vscode/launch.json in your project root and update the certificate paths in the Django_server configuration:
{
"version": "0.2.0",
"configurations": [
{
"name": "Django_server",
"type": "debugpy",
"request": "launch",
"python": "${workspaceFolder}/.venv/bin/python",
"program": "manage.py",
"args": [
"runsslserver",
"localhost:8000",
"--certificate",
"/Users/miniface/certs/localhost+2.pem", // ← Update this path
"--key",
"/Users/miniface/certs/localhost+2-key.pem" // ← Update this path
],
"django": true,
"justMyCode": true,
"env": {
"PYTHONUNBUFFERED": "1"
},
"cwd": "",
"console": "integratedTerminal"
}
]
}
Replace the paths after --certificate and --key with your actual certificate paths from the previous step.
Configure Vite with SSL certificates
Open frontend/vite.config.js in your project root and update the certificate paths at line 62 in the HTTPS configuration:
export default defineConfig({
server: {
// Development-only settings
...(process.env.NODE_ENV !== 'production' && {
https: {
key: fs.readFileSync(path.resolve(__dirname, '/path/to/your/localhost+2-key.pem')), // ← Update this path
cert: fs.readFileSync(path.resolve(__dirname, '/path/to/your/localhost+2.pem')), // ← Update this path
},
host: 'localhost',
port: 5173,
})
}
})
Replace /path/to/your/localhost+2-key.pem and /path/to/your/localhost+2.pem with your actual certificate paths from the mkcert step.
What is launch.json and how do I start the server?expand_more
The .vscode/launch.json file configures VS Code's debugger. The Django_server configuration tells VS Code how to start your Django development server with HTTPS support.
To start your backend server:
- Open your project in VS Code
- Press F5 or click the "Run and Debug" icon in the sidebar
- Select "Django_server" from the dropdown if it's not already selected
- The backend will start at
https://localhost:8000with debugging enabled
You can set breakpoints in your Python code, and the debugger will pause execution when they're hit.
Why HTTPS for local development?expand_more
Modern authentication flows (like OAuth with Google) require HTTPS, even in development. Without it, OAuth providers will reject your requests for security reasons.
Additionally, features like service workers, WebAuthn, and secure cookies require HTTPS to function properly.
What is mkcert and what does it do?expand_more
mkcert creates a local certificate authority (CA) on your machine and adds it to your system's trust store. This allows your browser to trust certificates signed by this CA.
When you run mkcert localhost 127.0.0.1 ::1, it generates SSL certificates for those addresses, enabling secure HTTPS connections to your local development servers without browser security warnings.
Install PostgreSQL
STEP 04Check if PostgreSQL is already installed
psql --version
If you see versions 15-17: Perfect! These are fully supported and all commands will work great. Production runs version 17.
If you see version 14: Still supported until Nov 2026, but consider upgrading soon. All commands will work fine.
If you see version 13 or older: These versions are end-of-life (EOL) and no longer receive security updates. We strongly recommend installing PostgreSQL 17.
If you see "command not found": PostgreSQL is not installed. Follow the installation instructions below.
macOS
Install PostgreSQL 17
brew install postgresql@17
This installs PostgreSQL 17 to match your production environment. Versions 15-17 all work perfectly.
Add PostgreSQL to your PATH
For zsh (default on modern macOS):
echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
For bash:
echo 'export PATH="/opt/homebrew/opt/postgresql@17/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
Linux
Install PostgreSQL 17
# Add PostgreSQL APT repository
sudo apt install -y postgresql-common
sudo sh /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
# Install PostgreSQL 17
sudo apt install -y postgresql-17 postgresql-contrib-17
This installs PostgreSQL 17 to match your production environment. Versions 15-17 all work perfectly.
Start PostgreSQL service
sudo systemctl start postgresql
Windows
Download and install PostgreSQL from the official PostgreSQL website.
Set your database name
export DB_NAME=local_otoshek
You can use any name you prefer. This will be the database backing your local development environment.
Start PostgreSQL service
brew services start postgresql@17
On Linux, run sudo systemctl start postgresql. On Windows, start the PostgreSQL service from the Services app.
Verify PostgreSQL is running
pg_isready -q || { echo "PostgreSQL is not accepting connections."; exit 1; }
Create the postgres superuser
createuser -s postgres
This creates a superuser named 'postgres' if it doesn't already exist. Safe to run multiple times.
Create the database
createdb -U postgres -O postgres "$DB_NAME"
This creates the database owned by the default PostgreSQL superuser.
Verify the database was created
psql -U postgres -tAc "SELECT datname FROM pg_database WHERE datname = '$DB_NAME'" | grep -qx "$DB_NAME"
This checks if the database exists. No output means success. If it fails, rerun the createdb command and ensure PostgreSQL is running.
Configure Django Database
STEP 05Open backend/settings.py and update your database configuration:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'local_otoshek', # Use the DB_NAME you exported earlier (export DB_NAME=local_otoshek)
'USER': 'postgres',
'PASSWORD': '', # Empty password for trusted local connections
'HOST': 'localhost',
'PORT': '5432',
'OPTIONS': {'sslmode': 'disable'},
}
}
Understanding Django database settingsexpand_more
- ENGINE selects the database backend (PostgreSQL for Otoshek).
- NAME is the database you created locally.
- USER/PASSWORD match the local PostgreSQL credentials.
- HOST and PORT point to your local server.
- OPTIONS disable SSL for local development.
Install Python 3.13 and Create Virtual Environment
STEP 06Check if Python 3.13 is already installed
python3.13 --version
If you see version 3.13.x, Python 3.13 is already installed and you can skip to creating the virtual environment. If you see "command not found", follow the OS-specific instructions below.
macOS
Install Python 3.13 (if not already installed)
brew install python@3.13
Linux
Install Python 3.13 (if not already installed)
sudo apt update
sudo apt install -y python3.13 python3.13-venv python3.13-dev
Windows
Download the Python 3.13 installer from the official Python website and make sure to enable "Add Python to PATH" during installation.
Create and activate virtual environment
Navigate to the root of your project (where manage.py is located) and run:
cd /path/to/your/project
python3.13 -m venv .venv
source .venv/bin/activate
On Windows PowerShell, run .\.venv\Scripts\activate instead.
Install Python dependencies
pip install -r requirements.txt
What is a virtual environment?expand_more
Virtual environments keep your project dependencies isolated so different projects can use their own versions of packages without conflicts.
Activating the environment ensures commands like python and pip reference the versions inside .venv.
Apply Database Migrations
STEP 07With your virtual environment activated and PostgreSQL running, apply the database migrations:
source .venv/bin/activate
python manage.py migrate
This creates all the necessary database tables for your Django application.
What are migrations?expand_more
Django migrations version-control your database schema so each environment stays in sync with your models.
Running python manage.py migrate applies any pending migrations in order.
Create Django Superuser
STEP 08Open a new terminal window at the root of your project and create an admin user to access the Django admin interface:
python manage.py createsuperuser
Follow the prompts to set a username, email (optional), and password. You'll use these credentials to log in to the admin at https://localhost:8000/admin.
Superuser permissions and usageexpand_more
A Django superuser has full access to the admin interface and can manage all database records, users, and settings. Use it to:
- Configure Stripe API keys
- Manage user accounts
- View and edit database records
- Test admin-only features
Configure Environment Variables
STEP 09Create a .env.development file at the root of your project and fill in the values you configured during infrastructure setup and got during deployment:
# Backend and Frontend URLs
FRONTEND_URL="https://localhost:5173"
BACKEND_URL="https://localhost:8000"
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# Email Configuration
DEFAULT_FROM_EMAIL=
MAILJET_API_URL=https://api.mailjet.com/v3.1/
MJ_APIKEY_PUBLIC=
MJ_APIKEY_PRIVATE=
# Stripe Price IDs (use these exact values from your deployment)
STRIPE_PREMIUM_MONTHLY_PRICE_ID=
STRIPE_PREMIUM_YEARLY_PRICE_ID=
STRIPE_STANDARD_MONTHLY_PRICE_ID=
STRIPE_STANDARD_YEARLY_PRICE_ID=
STRIPE_STARTER_MONTHLY_PRICE_ID=
STRIPE_STARTER_YEARLY_PRICE_ID=
# Stripe Webhook
STRIPE_WEBHOOK_SECRET=
Configure the assistant WebSocket for local HTTPS
Create frontend/.env.local so the frontend connects to the HTTPS-enabled Django backend with a secure WebSocket:
VITE_WEBSOCKET_URL_LOCAL=wss://localhost:8000
Where to find these valuesexpand_more
- Backend and Frontend URLs - Already set to localhost values, no changes needed
- Google OAuth - You configured these during infrastructure setup (Google Cloud Console credentials). Use the same Client ID and Secret.
- Email Configuration - You set these up during infrastructure setup (Mailjet API credentials). Use the same Mailjet keys.
- Stripe Price IDs - These were generated during deployment and displayed on screen. If you didn't copy them, you can find them in the dashboard by clicking the details of your successful deployment.
Add Stripe Test Key in Django Admin
STEP 10Configure Stripe for local development:
Install Python Debugger extension
Before starting the server, you need the Python Debugger extension installed in VS Code:
- Open VS Code Extensions: Code → Settings... → Extensions or press Shift+Cmd+X (Mac) / Shift+Ctrl+X (Windows/Linux)
- Search for "Python Debugger"
- Click Install on the official Python Debugger extension by Microsoft
Start the Django server
Press F5 in VS Code to start the Django server with the debugger configuration you set up earlier.
This will open a new terminal window in VS Code. Wait for the server to start successfully. You should see output similar to:
Starting development server at https://localhost:8000/
Using SSL certificate: /Users/miniface/certs/localhost+2.pem
Using SSL key: /Users/miniface/certs/localhost+2-key.pem
Quit the server with CONTROL-C.
- Navigate to
https://localhost:8000/adminin your browser - Log in with your superuser credentials
- Go to DJSTRIPE → API Keys
- Click Add API Key
- Paste your Stripe test secret key (starts with
sk_test_) in the "secret" field - Click Save
- Scroll down to Webhook endpoints and click it
- In the webhook endpoints page, select the Action dropdown
- Choose Sync All Instances for all API Keys
- Click Go
- Confirm the action on the confirmation page
- You should now see your production webhook URL (ending with
/stripe/webhooks/) listed in webhook endpoints
Test vs Live keysexpand_more
Stripe provides separate keys for test and live modes:
- Test keys (sk_test_...) - For development, no real charges are made
- Live keys (sk_live_...) - For production, processes real payments
Always use test keys in local development to avoid accidental charges.
Configure Webhook Secret
STEP 11Get your webhook signing secret from Stripe and add it to your local environment:
Get webhook secret from Stripe Dashboard
- Log in to your Stripe Dashboard
- Use the search bar at the top and search for "webhook"
- Select Webhooks from the results
- Click on your webhook (you should see one webhook that was created during deployment)
- On the webhook details page, find Signing secret on the right side
- Click Reveal and copy the secret (starts with
whsec_)
Add to your .env.development file
Open your .env.development file and add the webhook secret:
STRIPE_WEBHOOK_SECRET=whsec_...
Replace whsec_... with the actual webhook signing secret you copied from Stripe.
What are webhook secrets?expand_more
Stripe webhooks notify your application about events like successful payments, subscription changes, and failed charges. The webhook secret ensures that webhook requests actually come from Stripe and haven't been tampered with.
When Stripe sends a webhook to your application, it signs the request with this secret. Your application verifies the signature to confirm the request is legitimate.
Sync Stripe Data Locally
STEP 12Finally, sync your Stripe products, prices, and subscriptions to your local database:
python manage.py djstripe_sync_models price plan product customer subscription
This command pulls your Stripe test mode data into your local database, allowing you to test subscription flows without setting up products manually.
What data is being syncedexpand_more
- Products - Your subscription tiers (Starter, Standard, Premium)
- Prices - Monthly and yearly pricing for each tier
- Plans - Legacy subscription plans (if any)
- Customers - Test customer records
- Subscriptions - Active test subscriptions
This keeps your local development database in sync with your Stripe test account.
Install Node.js and Run Frontend
STEP 13Check if Node.js is already installed
node --version
If you see a version number (v18.x or higher recommended), Node.js is already installed. Otherwise, follow the instructions below.
macOS
Install Node.js (if not already installed)
brew install node
Linux
Install Node.js (if not already installed)
sudo apt install nodejs npm
Windows
Download and install Node.js from nodejs.org.
Install frontend dependencies
Navigate to the frontend directory from your project root and install dependencies:
cd frontend
npm install
Start the development server
npm run dev
The frontend will be available at https://localhost:5173.
Understanding the frontend build processexpand_more
The frontend uses Vite for lightning-fast hot module replacement (HMR). When you run npm run dev, Vite watches for file changes and reloads your browser instantly.
API requests are proxied to your Django backend on port 8000 so you can develop end-to-end features locally.
Access Your Application in the Browser
STEP 14With both servers running, you can now access your application in the browser.
Find the frontend URL in your terminal
Look at the terminal where npm run dev is running. You should see output that includes:
VITE v6.3.5 ready in 139 ms
➜ Local: https://localhost:5173/
➜ press h + enter to show help
Open the application
You can click the URL directly in the terminal while holding Cmd (Mac) / Ctrl (Windows/Linux). This will open the URL in your default browser.
Alternatively, manually navigate to: https://localhost:5173
What you should see
Your browser will load the application home page. You should be able to:
- See the application interface
- Sign in with Google OAuth
- Navigate through the application
- Test subscription features with Stripe test mode
🎉 Local environment ready
HANDOFFNext Steps
- Make changes to your code and watch them reload automatically
- Commit and push to trigger your CI/CD pipeline

