Ubuntu Installation Guide

Requirements

CodeHero requires Ubuntu 24.04 LTS specifically. Other Ubuntu versions or Debian derivatives are not officially supported.

Check Your Ubuntu Version

lsb_release -a

You should see Ubuntu 24.04 in the output.

Installation

Step 1: Update System Packages

sudo apt update
sudo apt install -y unzip wget net-tools

Step 2: Switch to Root

sudo su

Enter your password when prompted.

Step 3: Extract the CodeHero ZIP

Copy the ZIP file provided with your CodeHero PRO license to the server, then extract it:

cd /root
unzip codehero-pro-release-4.6.3.zip

Step 4: Run the Installer

cd codehero
chmod +x setup.sh
./setup.sh

The installer will automatically:

1. Install MySQL, Nginx, PHP-FPM, Python 3, and all dependencies
2. Create and configure the database
3. Set up the web interface with SSL
4. Create system services (codehero-web, codehero-daemon)
5. Configure firewall rules

Installation takes approximately 10-15 minutes depending on your internet speed.

Step 5: Note the Access Credentials

When the installer finishes, it displays the access URLs and default credentials. Write them down.

Post-Install Setup

Find Your IP Address

hostname -I

The first address shown is typically your server IP (e.g., 192.168.1.100).

Access the Dashboard

Open a browser on any device on the same network and navigate to:

https://YOUR_SERVER_IP:9453

Replace YOUR_SERVER_IP with the actual IP address.

Default Login Credentials

• Username: admin
• Password: admin123

Change Default Passwords (Important)

sudo /opt/codehero/scripts/change-passwords.sh

This changes both the web panel password and the database password.

Browser Security Warning

You will see a security warning because CodeHero uses a self-signed SSL certificate. This is expected and safe for local/private network use.

Install Claude Code CLI

After setup completes, install the Claude Code command-line tool:

/opt/codehero/scripts/install-claude-code.sh

Follow the prompts to authenticate with your Anthropic account.

Access URLs

Optional Extras

Development Tools (Node.js, Go, Rust, etc.)

Install additional development tools for broader project support:

/opt/codehero/scripts/install-devtools.sh

Android SDK (for mobile projects)

/opt/codehero/scripts/install-android.sh

Windows Cross-Compilation (Wine + .NET)

/opt/codehero/scripts/install-windows.sh

Language Servers (LSP support)

/opt/codehero/scripts/install-lsp.sh

Upgrading

To upgrade CodeHero to a newer version, extract the new ZIP file provided with your license update and run the upgrade script:

cd /root
unzip codehero-pro-release-4.6.3.zip
cd codehero
sudo ./upgrade.sh

The upgrade script preserves your projects, tickets, and configuration.

Uninstallation

To completely remove CodeHero:

sudo /opt/codehero/scripts/uninstall.sh

This removes:

• CodeHero application files (/opt/codehero)
• System services
• Database (optional, script will ask)
• Nginx configuration

Your project files in /var/www/projects and /opt/apps are not deleted by default.

Manual Cleanup (if uninstall script is unavailable)

# Stop services
sudo systemctl stop codehero-web codehero-daemon
sudo systemctl disable codehero-web codehero-daemon

# Remove service files
sudo rm /etc/systemd/system/codehero-web.service
sudo rm /etc/systemd/system/codehero-daemon.service
sudo systemctl daemon-reload

# Remove application
sudo rm -rf /opt/codehero

# Remove database (optional)
sudo mysql -e "DROP DATABASE IF EXISTS codehero;"

# Remove Nginx config
sudo rm /etc/nginx/sites-enabled/codehero*
sudo rm /etc/nginx/sites-available/codehero*
sudo systemctl restart nginx

Troubleshooting

Services Not Running

Check the status of CodeHero services:

sudo systemctl status codehero-web codehero-daemon

Restart them if needed:

sudo systemctl restart codehero-web codehero-daemon

Check all required services:

sudo systemctl status mysql nginx php8.3-fpm codehero-web codehero-daemon

Cannot Access Dashboard

1. Verify the server IP:

   hostname -I

2. Check if the web service is listening:

   sudo ss -tlnp | grep 9453

3. Check firewall rules:

   sudo ufw status
   sudo ufw allow 9453
   sudo ufw allow 9867

4. Review service logs:

   sudo journalctl -u codehero-web -n 50

MySQL Won't Start

sudo systemctl status mysql
sudo journalctl -u mysql -n 50

If disk is full:

df -h

Nginx Errors

sudo nginx -t
sudo journalctl -u nginx -n 50

Permission Issues

Ensure correct ownership:

sudo chown -R www-data:www-data /opt/codehero/web
sudo chown -R claude:claude /opt/codehero/heroagent

Check All Logs

# Web interface log
sudo journalctl -u codehero-web -f

# Daemon log
sudo journalctl -u codehero-daemon -f

# Nginx access/error logs
sudo tail -f /var/log/nginx/error.log