DEV Community

selfhosting.sh
selfhosting.sh

Posted on • Originally published at selfhosting.sh

Leantime

What Is Leantime?

Leantime is an open-source project management tool designed for non-project-managers. Where OpenProject and Taiga aim at experienced PM practitioners, Leantime focuses on startups, freelancers, and small teams who need to organize work without learning complex PM methodology. It includes Kanban boards, Gantt timelines, idea boards, retrospectives, and time tracking — wrapped in a cleaner, less overwhelming interface than most PM tools.

Specification Details
License AGPL-3.0 (open source) + proprietary cloud
Language PHP (Laravel)
Database MySQL 8.x
Latest Version v3.7.3
Docker Image leantime/leantime:3.7.3
Default Port 8080
Min RAM 512 MB
Recommended RAM 1-2 GB

Quick Verdict

Leantime is the best self-hosted PM tool for teams that find Jira and OpenProject overwhelming. It won't replace complex enterprise PM needs, but for small teams that need boards, timelines, and time tracking without a learning curve, it's the most approachable option available.

Use Cases

  • Freelancers tracking client projects with timelines and time logging
  • Startups that need organized work management without PM overhead
  • Creative teams using idea boards and retrospectives alongside task tracking
  • Small agencies managing multiple client projects with time tracking
  • Non-technical teams who need visual project management without Jira complexity

Prerequisites

  • A Linux server (Ubuntu 22.04+ recommended)
  • Docker and Docker Compose installed (guide)
  • 1 GB of RAM (512 MB minimum)
  • 5 GB of free disk space
  • A domain name (optional, for remote access)
Requirement Minimum Recommended
CPU 1 core 2 cores
RAM 512 MB 1-2 GB
Disk 5 GB 10 GB
Database MySQL 8.0+ MySQL 8.4

Docker Compose Configuration

Create a project directory:

mkdir -p ~/leantime && cd ~/leantime
Enter fullscreen mode Exit fullscreen mode

Create a docker-compose.yml:

services:
  leantime:
    image: leantime/leantime:3.7.3
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      LEAN_DB_HOST: db
      LEAN_DB_USER: leantime
      LEAN_DB_PASSWORD: "${DB_PASSWORD}"
      LEAN_DB_DATABASE: leantime
      LEAN_SESSION_PASSWORD: "${SESSION_PASSWORD}"
      LEAN_APP_URL: "${APP_URL}"
      # Optional: SMTP for email notifications
      # LEAN_EMAIL_RETURN: "noreply@example.com"
      # LEAN_EMAIL_USE_SMTP: "true"
      # LEAN_EMAIL_SMTP_HOSTS: "smtp.example.com"
      # LEAN_EMAIL_SMTP_PORT: "587"
      # LEAN_EMAIL_SMTP_USERNAME: "your-smtp-user"
      # LEAN_EMAIL_SMTP_PASSWORD: "your-smtp-password"
      # LEAN_EMAIL_SMTP_SECURE: "tls"
    volumes:
      - public-userfiles:/var/www/html/public/userfiles
      - userfiles:/var/www/html/userfiles
      - plugins:/var/www/html/app/Plugins
      - logs:/var/www/html/storage/logs
    depends_on:
      db:
        condition: service_healthy
    networks:
      - leantime-net

  db:
    image: mysql:8.4
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: leantime
      MYSQL_USER: leantime
      MYSQL_PASSWORD: "${DB_PASSWORD}"
      MYSQL_ROOT_PASSWORD: "${DB_ROOT_PASSWORD}"
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks:
      - leantime-net

volumes:
  db-data:
  public-userfiles:
  userfiles:
  plugins:
  logs:

networks:
  leantime-net:
    driver: bridge
Enter fullscreen mode Exit fullscreen mode

Create a .env file alongside docker-compose.yml:

# Database password — generate with: openssl rand -base64 32
DB_PASSWORD=change-me-strong-password

# MySQL root password
DB_ROOT_PASSWORD=change-me-root-password

# Session encryption key — generate with: openssl rand -base64 32
SESSION_PASSWORD=change-me-session-secret

# Your Leantime URL (used for links in emails and exports)
APP_URL=https://pm.example.com
Enter fullscreen mode Exit fullscreen mode

Start the stack:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Initial Setup

  1. Open http://your-server-ip:8080 in a browser
  2. The installer runs automatically on first visit
  3. Create your admin account (email + password)
  4. Configure your company name and time zone
  5. Create your first project

No database migration commands needed — Leantime handles schema creation automatically on first boot.

Configuration

Key Environment Variables

Variable Description Default
LEAN_DB_HOST MySQL hostname localhost
LEAN_DB_DATABASE Database name leantime
LEAN_SESSION_PASSWORD Session encryption key Required
LEAN_APP_URL Public URL for the instance http://localhost
LEAN_DEFAULT_TIMEZONE Server timezone America/Los_Angeles
LEAN_LANGUAGE Default language en-US
LEAN_SESSION_EXPIRATION Session timeout (seconds) 28800 (8 hours)
LEAN_LOG_LEVEL Logging verbosity error

SMTP Configuration

Email notifications require SMTP. Add these to your environment:

LEAN_EMAIL_RETURN=noreply@example.com
LEAN_EMAIL_USE_SMTP=true
LEAN_EMAIL_SMTP_HOSTS=smtp.example.com
LEAN_EMAIL_SMTP_PORT=587
LEAN_EMAIL_SMTP_USERNAME=your-smtp-user
LEAN_EMAIL_SMTP_PASSWORD=your-smtp-password
LEAN_EMAIL_SMTP_SECURE=tls
Enter fullscreen mode Exit fullscreen mode

Advanced Configuration

Plugins

Leantime supports plugins for extending functionality. Drop plugin folders into the plugins volume:

docker compose exec leantime ls /var/www/html/app/Plugins
Enter fullscreen mode Exit fullscreen mode

The plugin directory is persisted via the plugins volume, so plugins survive container restarts.

S3 File Storage

For large teams, offload file storage to S3-compatible storage:

LEAN_USE_S3=true
LEAN_S3_KEY=your-access-key
LEAN_S3_SECRET=your-secret-key
LEAN_S3_BUCKET=leantime-files
LEAN_S3_REGION=us-east-1
LEAN_S3_END_POINT=https://s3.amazonaws.com
Enter fullscreen mode Exit fullscreen mode

This works with MinIO, Wasabi, or any S3-compatible provider.

Reverse Proxy

Add Leantime to your reverse proxy. For Nginx Proxy Manager, create a proxy host pointing to http://leantime:8080. For Caddy:

pm.example.com {
    reverse_proxy leantime:8080
}
Enter fullscreen mode Exit fullscreen mode

See Reverse Proxy Setup for detailed configuration.

Backup

Back up these volumes:

  1. db-data — MySQL database (most critical)
  2. userfiles + public-userfiles — Uploaded files and attachments
  3. plugins — Installed plugins

Database backup:

docker compose exec db mysqldump -u leantime -p leantime > backup-$(date +%Y%m%d).sql
Enter fullscreen mode Exit fullscreen mode

See Backup Strategy for automated backup approaches.

Troubleshooting

Leantime shows a blank page after first login

Symptom: White screen or 500 error after creating admin account.
Fix: Check that LEAN_SESSION_PASSWORD is set in your .env file. Without it, session encryption fails silently. Restart the container after adding it:

docker compose restart leantime
Enter fullscreen mode Exit fullscreen mode

File uploads fail

Symptom: "Unable to upload file" when attaching files to tasks.
Fix: Check volume permissions. The container runs as www-data (UID 33). Ensure the volume mount points are writable:

docker compose exec leantime chown -R www-data:www-data /var/www/html/userfiles
docker compose exec leantime chown -R www-data:www-data /var/www/html/public/userfiles
Enter fullscreen mode Exit fullscreen mode

Database connection refused on startup

Symptom: Leantime exits with "Connection refused" to MySQL.
Fix: The depends_on with condition: service_healthy should handle this, but if MySQL is slow to start, increase the healthcheck start_period to 60s. Also verify your .env passwords match between the leantime and db service configurations.

Email notifications not sending

Symptom: Team members don't receive notification emails.
Fix: Verify SMTP credentials are correct. Test with a simple mail send:

docker compose exec leantime php -r "mail('test@example.com', 'Test', 'Body');"
Enter fullscreen mode Exit fullscreen mode

If PHP's mail() works but Leantime doesn't send, check that LEAN_EMAIL_USE_SMTP=true is set (not just the SMTP host).

Resource Requirements

Metric Value
RAM (idle) ~100-200 MB
RAM (active, 10 users) ~300-500 MB
CPU Low (PHP-FPM, minimal background work)
Disk (application) ~200 MB
Disk (database, 1K tasks) ~50 MB
Network Minimal (no federation, no real-time sync)

Leantime is lightweight. A 1 GB VPS handles a team of 20-30 users without issues.

Verdict

For teams that find OpenProject and Jira overwhelming, Leantime is the right tool. It delivers Kanban boards, Gantt timelines, time tracking, and idea management in a clean interface that non-technical team members can use immediately. It doesn't have OpenProject's depth in earned value management or Jira's 3,000-plugin ecosystem, but for small teams and freelancers, that's a feature — less complexity means less onboarding friction. If your PM needs are straightforward and you value simplicity, Leantime is the self-hosted option to start with.

FAQ

How does Leantime compare to OpenProject?

OpenProject is more feature-rich (Gantt, BIM, cost reporting, LDAP) and targets experienced PM practitioners. Leantime is simpler and more approachable, targeting small teams and non-project-managers. See OpenProject for a full guide.

Can Leantime handle large teams (100+ users)?

Leantime can support 100+ users technically, but it's designed for small-to-medium teams (5-50). For larger organizations, OpenProject or Taiga are better suited.

Does Leantime support two-factor authentication?

The open-source version does not include built-in 2FA. You can add authentication at the reverse proxy level using Authelia or similar tools.

Is Leantime actively maintained?

Yes. The latest release is v3.7.3 (February 2025). Development is active with regular releases. The project is backed by Leantime Inc., which offers a cloud-hosted version.

Related

Top comments (0)