# Plane.io Setup Guide - Ubuntu 24.04 LTS (Localhost)

Complete guide for running Plane.io locally on Ubuntu 24.04 LTS.

## 🐧 Prerequisites for Ubuntu 24.04 LTS

- Ubuntu 24.04 LTS (fresh install recommended)
- 4GB RAM minimum (8GB recommended)
- 10GB free disk space
- Internet connection for initial setup
- sudo privileges

## 🚀 Quick Installation (Recommended)

### Step 1: Install Docker (if not already installed)

# Update package index
sudo apt update

# Install Docker using the official script (easiest method)
curl -fsSL https://get.docker.com | sudo sh

# Add your user to docker group (to run docker without sudo)
sudo usermod -aG docker $USER

# Start and enable Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Log out and log back in (or reboot) for group changes to take effect
# Or run: newgrp docker

### Step 2: Verify Docker Installation

# Check Docker version
docker --version

# Test Docker (should download and run hello-world)
docker run hello-world

### Step 3: Install Plane.io (Commercial Edition - Easiest)

# Create directory for Plane
mkdir ~/plane-local
cd ~/plane-local

# Run the official installer
curl -fsSL https://prime.plane.so/install/ | sh -

**Installation Prompts:**
1. Press **Enter** to continue
2. **Domain**: Enter `localhost` or `127.0.0.1`
3. **Installation Type**: Choose `Express` (recommended for localhost)

### Step 4: Access Your Local Plane Instance

After installation completes (5-10 minutes):
- Open Firefox/Chrome
- Navigate to: **http://localhost**
- Create your admin account
- Start using Plane!

## 🛠️ Alternative: Manual Community Edition Setup

If you prefer the Community Edition:

# Create installation directory
mkdir ~/plane-local
cd ~/plane-local

# Download setup script
curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh

# Make executable
chmod +x setup.sh

# Run setup
./setup.sh

**Setup Process:**
1. Select option `1` (Install - arm64 for ARM or regular for x64)
2. Wait for download to complete
3. Select option `8` (Exit)
4. Configure environment (optional)
5. Run `./setup.sh` again and select option `2` (Start)

### Configuration for Localhost (Optional)

Edit the environment file if needed:

cd plane-app
nano plane.env

Key settings for localhost:

LISTEN_HTTP_PORT=80
LISTEN_HTTPS_PORT=443
WEB_URL=http://localhost
CORS_ALLOWED_ORIGINS=http://localhost

# If port 80 is busy, use alternative port:
# LISTEN_HTTP_PORT=8080
# WEB_URL=http://localhost:8080
# CORS_ALLOWED_ORIGINS=http://localhost:8080

## 📊 Verify Installation

# Check running containers
docker ps

# You should see containers like:
# plane-app-web-1        (Frontend)
# plane-app-api-1        (Backend API)
# plane-app-worker-1     (Background worker)
# plane-app-beat-worker-1 (Scheduler)
# plane-app-migrator-1   (Database migrations)
# plane-app-db-1         (PostgreSQL)
# plane-app-redis-1      (Redis cache)
# plane-app-minio-1      (File storage)

## 🔧 Management Commands

cd ~/plane-local

# View all options
./setup.sh

# Available options:
# 1) Install
# 2) Start      ← Use this to start services
# 3) Stop       ← Use this to stop services  
# 4) Restart    ← Use this to restart services
# 5) Upgrade    ← Use this to update Plane
# 6) View Logs  ← Use this to see logs
# 7) Backup Data ← Use this to backup
# 8) Exit

## 🌐 Access Points

After successful setup:
- **Main Application**: http://localhost
- **MinIO Console**: http://localhost:9000
- Username: `minioadmin`
- Password: `minioadmin`

## 🛠️ Troubleshooting Ubuntu Issues

### Port 80 Already in Use

# Check what's using port 80
sudo lsof -i :80

# If Apache2 is running:
sudo systemctl stop apache2
sudo systemctl disable apache2

# Or change Plane port in plane.env:
LISTEN_HTTP_PORT=8080
WEB_URL=http://localhost:8080

### Docker Permission Issues

# Add user to docker group
sudo usermod -aG docker $USER

# Restart session or run:
newgrp docker

# Or use sudo for docker commands
sudo docker ps

### Firewall Issues (if using UFW)

# Allow port 80 (if firewall is enabled)
sudo ufw allow 80/tcp

# Check firewall status
sudo ufw status

### Service Not Starting

# Check Docker service
sudo systemctl status docker

# Restart Docker if needed
sudo systemctl restart docker

# Check logs
cd ~/plane-local/plane-app
docker-compose logs

### Low Memory Issues

# Check available memory
free -h

# If low on RAM, create swap file
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent by adding to /etc/fstab
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

## 🔄 Starting/Stopping Plane

# Start Plane (run this after reboot)
cd ~/plane-local
./setup.sh
# Select option 2

# Stop Plane (to free resources)
./setup.sh
# Select option 3

# View status
docker ps

## 🚀 Auto-start on Boot (Optional)

To start Plane automatically when Ubuntu boots:

# Create systemd service
sudo nano /etc/systemd/system/plane.service

Add this content:

[Unit]
Description=Plane.io Self-hosted
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=true
WorkingDirectory=/home/YOUR_USERNAME/plane-local/plane-app
ExecStart=/usr/bin/docker-compose up -d
ExecStop=/usr/bin/docker-compose down
User=YOUR_USERNAME
Group=docker

[Install]
WantedBy=multi-user.target

Replace `YOUR_USERNAME` with your actual username, then:

# Enable the service
sudo systemctl enable plane.service

# Start it
sudo systemctl start plane.service

## 💡 Ubuntu Advantages

✅ **Native Docker support** - no WSL2 needed
✅ **Better performance** than Windows containers
✅ **Lower resource usage**
✅ **More stable** for long-running services
✅ **Easy command-line management**
✅ **Perfect for development servers**

## 🎯 Quick Summary

**For Ubuntu 24.04 LTS localhost setup:**

1. **Install Docker**: `curl -fsSL https://get.docker.com | sudo sh`
2. **Add user to docker group**: `sudo usermod -aG docker $USER`
3. **Reboot or logout/login**
4. **Install Plane**: `curl -fsSL https://prime.plane.so/install/ | sh -`
5. **Enter domain**: `localhost`
6. **Choose**: Express installation
7. **Access**: http://localhost

Your local Plane.io instance will be ready in 5-10 minutes! 🚀

## 📚 Next Steps

After installation:
- Create your workspace
- Set up projects
- Invite team members (if needed)
- Configure integrations
- Explore Plane's features

Perfect for personal project management or team collaboration on your local network!