Installation

Server Requirements

Before installing Wecode, ensure your Linux server meets the following requirements:

PHP Requirements

Wecode is built with Laravel 12, which requires PHP 8.0.2 or higher.

Required PHP extensions (inherited from Laravel server requirements):

PHP >= 8.0.2
BCMath PHP Extension
Ctype PHP Extension
Fileinfo PHP Extension
JSON PHP Extension
Mbstring PHP Extension
OpenSSL PHP Extension
PDO PHP Extension
Tokenizer PHP Extension
XML PHP Extension

Critical PHP Configuration:

PHP must have permission to run shell commands using shell_exec() function
Specifically, shell_exec("php") must work correctly

Verify shell_exec is enabled:

php -r "echo shell_exec('php -v');"

Database

MySQL or PostgreSQL database server
Database user with CREATE, ALTER, INSERT, UPDATE, DELETE, SELECT privileges

Docker

Docker is required for secure code execution. While Wecode can technically use native compilation tools, this poses a severe security risk and is planned to be removed.

Docker CE (Community Edition) installed and running
Web server user must have permission to manage Docker containers

Additional Tools

Composer: PHP dependency manager (can be installed by the install script)
Perl: Recommended for more precise time and memory limits and output size restrictions
Git: For cloning the repository

System Resources

Sufficient disk space for:
- Source code (~50-100 MB)
- Docker images (~500 MB - 2 GB depending on languages)
- Student submissions (varies by usage)
Adequate RAM for running Docker containers concurrently (recommended: 2 GB minimum)

Installation Methods

Wecode provides two installation scripts:

install.sh: Simple installation with database configuration
setup.sh: Advanced installation with separate install and public directories

Method 1: Simple Installation (install.sh)

Best for development or simple deployments where the entire application is in one directory.

Clone the Repository

cd /var/www
git clone https://github.com/truongan/wecode.git
cd wecode

Create Database

Create a database and user for Wecode:For MySQL:

CREATE DATABASE wecode;
CREATE USER 'wecode_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON wecode.* TO 'wecode_user'@'localhost';
FLUSH PRIVILEGES;

For PostgreSQL:

createdb wecode
createuser wecode_user

Run install.sh

Execute the installation script:

./install.sh -u wecode_user -d wecode -p your_password -s "http://your-domain.com"

Full options:

./install.sh -a admin_username \
             -e [email protected] \
             -u db_user \
             -d db_name \
             -p db_password \
             -s "http://your-domain.com"

-a  Admin username (default: "abc")
-e  Admin email (default: "[email protected]")
-u  Database username (required)
-d  Database name (defaults to username)
-p  Database password (required)
-s  Site URL with http:// or https:// (required)
-h  Show help message

What install.sh Does

The script automatically:

Downloads and verifies Composer
Runs composer install to install PHP dependencies
Copies .env.example to .env
Updates .env with your database credentials and site URL
Generates Laravel application key with php artisan key:generate
Runs database migrations with php artisan migrate:refresh
Seeds initial data with php artisan db:seed --class=installation_seeding
Creates admin users with php artisan add_admin

The script creates two admin accounts: one default account (truonganpn) and your custom account.

Method 2: Advanced Installation (setup.sh)

Best for production deployments with separate installation and public directories.

Prepare Directories

Create separate directories for installation and public files:

sudo mkdir -p /opt/wecode
sudo mkdir -p /var/www/html

Download setup.sh

Download the setup script:

cd /opt/wecode
wget https://raw.githubusercontent.com/truongan/wecode/master/setup.sh
chmod +x setup.sh

Run setup.sh

Execute with custom directories:

./setup.sh -i /opt/wecode \
           -o /var/www/html \
           -u wecode_user \
           -p db_password \
           -d wecode \
           -n "My Wecode Instance" \
           "https://your-domain.com"

Options:

-i  Install directory (default: current directory)
-o  Public directory for index.php (default: ../public_html)
-u  Database username (required)
-p  Database password (required)
-d  Database name (defaults to username)
-n  Site name to display (default: "Wecode-Judge")
-a  Default admin username
-h  Show help message

The last argument is the base URL (required if -n not specified).

What setup.sh Does

This script:

Clones the Wecode repository to the install directory
Creates symbolic links from public directory to install/public
Calls install.sh to complete the installation

This method keeps your source code separate from the web-accessible directory, improving security.

Manual Database Configuration

If you prefer to configure the database manually instead of using the install scripts:

Copy Environment File

cp .env.example .env

Edit .env File

Open .env and configure database settings:

.env

APP_NAME=Wecode
APP_ENV=production
APP_KEY=  # Will be generated
APP_DEBUG=false
APP_URL=http://your-domain.com

DB_CONNECTION=mysql  # or pgsql for PostgreSQL
DB_HOST=127.0.0.1
DB_PORT=3306  # or 5432 for PostgreSQL
DB_DATABASE=wecode
DB_USERNAME=wecode_user
DB_PASSWORD=your_password

Install Dependencies

composer install --no-dev --optimize-autoloader

Generate Application Key

php artisan key:generate

Run Migrations

php artisan migrate
php artisan db:seed --class=installation_seeding

Create Admin User

php artisan add_admin username [email protected] password

Docker Setup

Docker is essential for secure code execution in Wecode.

Install Docker CE

Follow the official Docker installation guide for your Linux distribution:For Ubuntu:

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install ca-certificates curl gnupg lsb-release

# Add Docker's GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

See Docker installation guide for other distributions.

Configure Docker Permissions

Allow the web server user to manage Docker:

# Add www-data to docker group
sudo usermod -aG docker www-data

# Verify the user is in the group
groups www-data

You must restart your web server after adding the user to the docker group for changes to take effect.

# Restart Apache
sudo systemctl restart apache2

# OR restart Nginx + PHP-FPM
sudo systemctl restart nginx
sudo systemctl restart php8.0-fpm

See Docker post-installation steps for more details.

Test Docker Access

Verify the web server can use Docker:

sudo -u www-data docker ps

This should list running containers without errors.

Pull Required Images

Pull Docker images for the programming languages you plan to support:

docker pull gcc:latest       # For C/C++
docker pull python:latest    # For Python
docker pull openjdk:latest   # For Java

Web Server Configuration

Apache Configuration

Enable Required Modules

sudo a2enmod rewrite
sudo systemctl restart apache2

Create Virtual Host

Create /etc/apache2/sites-available/wecode.conf:

<VirtualHost *:80>
    ServerName wecode.yourdomain.com
    DocumentRoot /var/www/wecode/public
    
    <Directory /var/www/wecode/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/wecode_error.log
    CustomLog ${APACHE_LOG_DIR}/wecode_access.log combined
</VirtualHost>

Enable Site

sudo a2ensite wecode.conf
sudo systemctl reload apache2

Nginx Configuration

Create Server Block

Create /etc/nginx/sites-available/wecode:

server {
    listen 80;
    listen [::]:80;
    server_name wecode.yourdomain.com;
    root /var/www/wecode/public;
    
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    
    index index.php;
    
    charset utf-8;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
    
    error_page 404 /index.php;
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable Site

sudo ln -s /etc/nginx/sites-available/wecode /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Post-Installation Configuration

CRITICAL SECURITY STEP: You must move the assignments and tester folders outside the public directory.

Move Sensitive Folders

# Create secure directory
sudo mkdir -p /var/wecode-data

# Move folders from installation directory
sudo mv /var/www/wecode/tester /var/wecode-data/
sudo mv /var/www/wecode/assignments /var/wecode-data/

# Set ownership to web server user
sudo chown -R www-data:www-data /var/wecode-data

# Set permissions (must be writable by PHP)
sudo chmod -R 755 /var/wecode-data
sudo chmod -R 775 /var/wecode-data/assignments
sudo chmod -R 775 /var/wecode-data/tester

The assignments folder will store all submitted code files. The tester folder contains test cases and grading scripts. Both must be writable by the web server user.

Update Folder Paths in Wecode

Login to Wecode as admin
Navigate to Settings page
Update the paths:
- Assignments folder: /var/wecode-data/assignments
- Tester folder: /var/wecode-data/tester
Save settings

Set File Permissions

Ensure proper permissions on the installation directory:

cd /var/www/wecode
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

Configure Environment for Production

Edit .env for production settings:

APP_ENV=production
APP_DEBUG=false
APP_ARCHIVED=false

Clear and optimize caches:

php artisan config:cache
php artisan route:cache
php artisan view:cache

Troubleshooting Common Issues

Issue: “Class not found” or Composer Errors

Solution:

composer install --no-dev
composer dump-autoload
php artisan clear-compiled
php artisan config:clear

Issue: Database Connection Failed

Solution:

Verify database credentials in .env
Test database connection:
```
mysql -u wecode_user -p wecode
```
Check if database exists:
```
SHOW DATABASES;
```

Verify user permissions:

SHOW GRANTS FOR 'wecode_user'@'localhost';

Issue: Docker Permission Denied

Solution:

# Verify www-data is in docker group
groups www-data

# If not, add it
sudo usermod -aG docker www-data

# Restart web server
sudo systemctl restart apache2  # or nginx + php-fpm

# Test as www-data user
sudo -u www-data docker ps

Issue: shell_exec() Disabled

Solution:

Check php.ini for disable_functions:
```
php -i | grep disable_functions
```
Remove shell_exec from disabled functions
Restart web server

Enabling shell_exec() has security implications. Ensure Wecode is the only application running on this server, or implement additional security measures.

Issue: File Upload Errors

Solution: Increase PHP upload limits in php.ini:

upload_max_filesize = 20M
post_max_size = 20M
max_execution_time = 300

Restart web server after changes.

Issue: Submission Queue Not Processing

Solution:

Check Docker is running:
```
sudo systemctl status docker
```
Verify web server can execute Docker:
```
sudo -u www-data docker ps
```

Check PHP error logs:

tail -f /var/log/apache2/wecode_error.log

Check Laravel logs:

tail -f /var/www/wecode/storage/logs/laravel.log

Issue: Permissions Errors on assignments/tester Folders

Solution:

sudo chown -R www-data:www-data /var/wecode-data
sudo chmod -R 775 /var/wecode-data/assignments
sudo chmod -R 775 /var/wecode-data/tester

# Test write permissions
sudo -u www-data touch /var/wecode-data/assignments/test.txt
sudo -u www-data rm /var/wecode-data/assignments/test.txt

Security Hardening

After installation, follow these security best practices:

Read Security Guide

Complete security hardening guide

Enable HTTPS

Use Let’s Encrypt or another SSL certificate provider

Essential security steps:

Move assignments and tester folders outside public directory
Set APP_DEBUG=false in production
Use strong database passwords
Enable HTTPS with valid SSL certificate
Configure firewall to restrict access
Regularly update dependencies: composer update
Regular database backups
Monitor logs for suspicious activity

Getting Started

Core Features

Advanced Features

Configuration

User Guides

Server Requirements

PHP Requirements

Database

Docker

Additional Tools

System Resources

Installation Methods

Method 1: Simple Installation (install.sh)

Method 2: Advanced Installation (setup.sh)

Manual Database Configuration

Docker Setup

Web Server Configuration

Apache Configuration

Nginx Configuration

Post-Installation Configuration

Troubleshooting Common Issues

Issue: “Class not found” or Composer Errors

Issue: Database Connection Failed

Issue: Docker Permission Denied

Issue: shell_exec() Disabled

Issue: File Upload Errors

Issue: Submission Queue Not Processing

Issue: Permissions Errors on assignments/tester Folders

Security Hardening

Read Security Guide

Enable HTTPS

Next Steps

Full Documentation

Quickstart Guide

Build docs developers (and LLMs) love

Getting Started

Core Features

Advanced Features

Configuration

User Guides

​Server Requirements

​PHP Requirements

​Database

​Docker

​Additional Tools

​System Resources

​Installation Methods

​Method 1: Simple Installation (install.sh)

​Method 2: Advanced Installation (setup.sh)

​Manual Database Configuration

​Docker Setup

​Web Server Configuration

​Apache Configuration

​Nginx Configuration

​Post-Installation Configuration

​Troubleshooting Common Issues

​Issue: “Class not found” or Composer Errors

​Issue: Database Connection Failed

​Issue: Docker Permission Denied

​Issue: shell_exec() Disabled

​Issue: File Upload Errors

​Issue: Submission Queue Not Processing

​Issue: Permissions Errors on assignments/tester Folders

​Security Hardening

Read Security Guide

Enable HTTPS

​Next Steps

Full Documentation

Quickstart Guide

Build docs developers (and LLMs) love

Server Requirements

PHP Requirements

Database

Docker

Additional Tools

System Resources

Installation Methods

Method 1: Simple Installation (install.sh)

Method 2: Advanced Installation (setup.sh)

Manual Database Configuration

Docker Setup

Web Server Configuration

Apache Configuration

Nginx Configuration

Post-Installation Configuration

Troubleshooting Common Issues

Issue: “Class not found” or Composer Errors

Issue: Database Connection Failed

Issue: Docker Permission Denied

Issue: shell_exec() Disabled

Issue: File Upload Errors

Issue: Submission Queue Not Processing

Issue: Permissions Errors on assignments/tester Folders

Security Hardening

Next Steps