Codakey
Play
← Back to AdventureLog

How to Deploy & Use AdventureLog

AdventureLog Deployment & Usage Guide

1. Prerequisites

Runtime & Database

  • Node.js 18+ (for SvelteKit frontend)
  • Python 3.10+ (for Django backend)
  • PostgreSQL 13+ with PostGIS extension
  • Redis (for caching and background tasks, optional but recommended)

Tools

  • npm or yarn (Node package manager)
  • pip (Python package manager)
  • Git (for cloning the repository)
  • Docker and Docker Compose (optional, for containerized deployment)

Accounts & API Keys (Optional)

  • MapLibre/MapTiler account for map tiles (or use free OpenStreetMap)
  • Immich instance for photo integration (optional)
  • Email service (SMTP) for user registration and notifications
  • Social authentication providers (Google, GitHub, etc.) if desired

2. Installation

Clone the Repository

git clone https://github.com/seanmorley15/AdventureLog.git
cd AdventureLog

Backend Setup (Django)

# Navigate to backend directory
cd backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Install PostGIS development libraries (Ubuntu/Debian)
sudo apt-get install libpq-dev postgresql-client postgis

# Install PostGIS development libraries (macOS)
brew install postgresql postgis

Frontend Setup (SvelteKit)

# Navigate to frontend directory
cd frontend

# Install Node.js dependencies
npm install  # or yarn install

3. Configuration

Environment Variables

Create .env files in both backend/ and frontend/ directories:

Backend .env (backend/.env):

# Database
DATABASE_URL=postgis://username:password@localhost:5432/adventurelog
SECRET_KEY=your-secret-key-here

# Email (optional)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
DEFAULT_FROM_EMAIL=your-email@gmail.com

# CORS and URLs
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
PUBLIC_SERVER_URL=http://localhost:8000
PUBLIC_CLIENT_URL=http://localhost:5173

# Map Configuration
MAPTILER_API_KEY=your-maptiler-key  # Optional
DEFAULT_MAP_STYLE=streets-v2

# Immich Integration (optional)
IMMICH_API_KEY=your-immich-api-key
IMMICH_INSTANCE_URL=https://your-immich.instance

# Security
DEBUG=False  # Set to False in production
ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.com

Frontend .env (frontend/.env):

PUBLIC_SERVER_URL=http://localhost:8000
PUBLIC_CLIENT_URL=http://localhost:5173
PUBLIC_MAPTILER_API_KEY=your-maptiler-key  # Optional

Database Setup

  1. Create PostgreSQL database with PostGIS:
CREATE DATABASE adventurelog;
\c adventurelog
CREATE EXTENSION postgis;
CREATE EXTENSION postgis_topology;
  1. Run Django migrations:
cd backend
python manage.py migrate
  1. Create superuser (optional):
python manage.py createsuperuser
  1. Load initial data (countries, regions):
python manage.py loaddata countries regions

4. Build & Run

Development Mode

Start Backend Server:

cd backend
python manage.py runserver
# Server runs on http://localhost:8000

Start Frontend Development Server:

cd frontend
npm run dev
# Frontend runs on http://localhost:5173

Access the application at http://localhost:5173

Production Build

Build Frontend:

cd frontend
npm run build
# Outputs to frontend/build directory

Serve Production Build:

# Option 1: Use SvelteKit adapter-node
npm run build
node build/index.js

# Option 2: Use a reverse proxy (nginx, Caddy) to serve static files

Run Backend in Production:

cd backend
# Use production WSGI server
gunicorn adventurelog.wsgi:application --bind 0.0.0.0:8000 --workers 4

# With environment variables
gunicorn adventurelog.wsgi:application --bind 0.0.0.0:$PORT --workers $WEB_CONCURRENCY

5. Deployment

Docker Deployment (Recommended)

The project includes Docker support. Use the provided docker-compose.yml:

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Platform Recommendations

For Backend (Django):

  • Railway.app - Easy Django/PostgreSQL deployment
  • Render.com - Free tier available, supports PostgreSQL with PostGIS
  • Heroku (with PostGIS add-on)
  • DigitalOcean App Platform or Droplet
  • AWS Elastic Beanstalk with RDS PostgreSQL + PostGIS

For Frontend (SvelteKit):

  • Vercel - Excellent SvelteKit support
  • Netlify - Simple static deployment
  • Cloudflare Pages
  • GitHub Pages (for static adapter)
  • Same platform as backend (served from Django static files)

Full-Stack Deployment Example (Render.com)

  1. Create a new Web Service on Render
  2. Connect your GitHub repository
  3. Use these build settings: 
    Build Command: cd frontend && npm run build
Start Command: cd backend && gunicorn adventurelog.wsgi:application --bind 0.0.0.0:$PORT
  4. Add environment variables from Configuration section
  5. Add PostgreSQL database with PostGIS extension

Database Considerations

  • Ensure your PostgreSQL provider supports PostGIS extension
  • For Railway/Render: Use their PostgreSQL service and enable PostGIS via CREATE EXTENSION postgis;
  • For Heroku: Use PostGIS add-on: heroku addons:create heroku-postgresql:standard-0
  • Regular backups recommended for production data

6. Troubleshooting

Common Issues

1. "PostGIS extension not available"

# Ensure PostGIS is installed in your PostgreSQL
sudo apt-get install postgresql-13-postgis-3  # Adjust version
# Then connect to database and run:
CREATE EXTENSION postgis;

2. Frontend can't connect to backend (CORS errors)

  • Verify CORS_ALLOWED_ORIGINS includes your frontend URL
  • Check PUBLIC_SERVER_URL and PUBLIC_CLIENT_URL environment variables
  • Ensure both servers are running on correct ports

3. Authentication/session issues

  • Clear browser cookies for the domain
  • Check that SECRET_KEY is set and consistent
  • Verify session cookies are being set properly in browser dev tools

4. Map not loading

  • Check if PUBLIC_MAPTILER_API_KEY is set in frontend
  • Try a different map style in backend .env: DEFAULT_MAP_STYLE=osm-liberty
  • Verify network requests in browser console for map tile errors

5. Database connection failures

# Test database connection
python manage.py dbshell

# Check database URL format
# Correct: postgis://user:pass@host:port/dbname
# Not: postgres://...

6. Static files not loading in production

# Collect static files
python manage.py collectstatic

# Ensure STATIC_ROOT is set in settings.py
# Verify web server (nginx, etc.) is configured to serve static files

7. "Module not found" errors

# Reinstall dependencies
cd frontend && npm install
cd backend && pip install -r requirements.txt

# Clear npm cache if needed
npm cache clean --force

Logs & Debugging

Backend logs:

# Django debug logs
tail -f backend/logs/debug.log

# Gunicorn logs
journalctl -u gunicorn -f  # Systemd

Frontend logs:

  • Check browser developer console (F12)
  • Build errors: npm run build output
  • Runtime errors in browser console

Database queries:

# Enable SQL logging in Django
# Add to settings.py:
LOGGING = {
    'version': 1,
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django.db.backends': {
            'level': 'DEBUG',
            'handlers': ['console'],
        },
    },
}

Getting Help

← Project overviewView alternatives to AdventureLog →