feat: Add Docker and Codespaces development environments

.devcontainer/Dockerfile

@@ -0,0 +1,44 @@
+# .devcontainer/Dockerfile
+FROM mcr.microsoft.com/vscode/devcontainers/php:8.2
+
+# Install system dependencies
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+    && apt-get -y install --no-install-recommends \
+    libpq-dev \
+    libpng-dev \
+    libjpeg-dev \
+    libzip-dev
+
+# Install PHP extensions
+RUN docker-php-ext-install \
+    pdo_pgsql \
+    bcmath \
+    gd \
+    zip
+
+# Install Node.js
+RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs
+
+# [Optional] Set the default user. Omit if you want to keep the default as root.
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+RUN if [ "$USER_UID" -ne "0" ]; then \
+    groupadd --gid $USER_GID vscode \
+    && useradd --uid $USER_UID --gid $USER_GID -m vscode \
+    && apt-get install -y sudo \
+    && echo vscode ALL=\(ALL\) NOPASSWD:ALL > /etc/sudoers.d/vscode \
+    && chmod 0440 /etc/sudoers.d/vscode; \
+    fi
+
+# Add aliases to .bashrc
+RUN echo '' >> /home/vscode/.bashrc && \
+    echo '# Custom aliases' >> /home/vscode/.bashrc && \
+    echo 'alias pa="php artisan"' >> /home/vscode/.bashrc && \
+    echo 'alias pest="./vendor/bin/pest"' >> /home/vscode/.bashrc && \
+    echo 'alias pint="./vendor/bin/pint"' >> /home/vscode/.bashrc && \
+    echo 'alias format="composer format"' >> /home/vscode/.bashrc && \
+    echo 'alias test="composer test"' >> /home/vscode/.bashrc
+
+# Switch to the non-root user
+USER vscode

.devcontainer/devcontainer.json

@@ -1,17 +1,20 @@
 {
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-20.04",
-  "features": {
-    "ghcr.io/devcontainers/features/php:1": {
-      "version": "8.2",
-      "installComposer": true
-    }
-  },
-  "postCreateCommand": "sudo apt update && sudo apt install -y libssl1.1",
+  "name": "OTE v2 Dev Container",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "app",
+  "workspaceFolder": "/workspace",
+
+  "postCreateCommand": "composer install && cp .env.example .env && php artisan key:generate && php artisan migrate && php artisan db:seed",
+
   "customizations": {
     "vscode": {
       "extensions": [
-        "bmewburn.vscode-intelephense-client"
+        "bmewburn.vscode-intelephense-client",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode"
       ]
     }
-  }
+  },
+
+  "remoteUser": "vscode"
 }

.devcontainer/docker-compose.yml

@@ -0,0 +1,38 @@
+# .devcontainer/docker-compose.yml
+version: '3'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    volumes:
+      - ..:/workspace:cached
+    ports:
+      - 8000:8000
+    depends_on:
+      - db
+      - redis
+    environment:
+      - DB_CONNECTION=pgsql
+      - DB_HOST=db
+      - DB_PORT=5432
+      - DB_DATABASE=laravel
+      - DB_USERNAME=laravel
+      - DB_PASSWORD=secret
+      - REDIS_HOST=redis
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      - POSTGRES_DB=laravel
+      - POSTGRES_USER=laravel
+      - POSTGRES_PASSWORD=secret
+    volumes:
+      - ote-db-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+
+volumes:
+  ote-db-data:

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.env
+.idea
+.vscode
+node_modules
+vendor
+storage/logs
+storage/framework/sessions
+storage/framework/cache
+storage/framework/views
+docker

README.md

@@ -87,3 +87,129 @@ Multilingual Online Resources for Minority Languages of a Campus Community
 ## License
 
 The Open Translation Engine is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
+
+## Development Environment with Docker
+
+This project includes a Docker-based development environment that allows you to run the application and its dependencies in isolated containers.
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+- [Docker Compose](https://docs.docker.com/compose/install/)
+
+### Setup
+
+1.  **Build and start the containers:**
+
+    ```bash
+    docker compose -f compose.dev.yml up --build -d
+    ```
+
+    This command will build the Docker images and start the services in detached mode.
+
+2.  **Install Composer dependencies:**
+
+    Open a new terminal and run the following command to install the PHP dependencies using Composer.
+
+    ```bash
+    docker compose -f compose.dev.yml exec workspace composer install
+    ```
+
+3.  **Copy the environment file:**
+
+    ```bash
+    cp .env.example .env
+    ```
+
+4.  **Generate the application key:**
+
+    ```bash
+    docker compose -f compose.dev.yml exec workspace php artisan key:generate
+    ```
+
+5.  **Run database migrations:**
+
+    ```bash
+    docker compose -f compose.dev.yml exec workspace php artisan migrate
+    ```
+
+6.  **Seed the database (optional):**
+
+    To populate the database with sample data, run the following command:
+    ```bash
+    docker compose -f compose.dev.yml exec workspace php artisan db:seed
+    ```
+
+### Usage
+
+-   **Accessing the application:**
+
+    Once the containers are running, you can access the application in your web browser at [http://localhost](http://localhost).
+
+-   **Running Artisan commands:**
+
+    To run any `artisan` command, use `docker compose exec workspace php artisan <command>`. For example:
+
+    ```bash
+    docker compose -f compose.dev.yml exec workspace php artisan route:list
+    ```
+
+-   **Running Composer commands:**
+
+    To run any `composer` command, use `docker compose exec workspace composer <command>`. For example:
+
+    ```bash
+    docker compose -f compose.dev.yml exec workspace composer update
+    ```
+
+-   **Running NPM commands:**
+
+    To run any `npm` command, use `docker compose exec workspace npm <command>`. For example, to compile the frontend assets:
+
+    ```bash
+    docker compose -f compose.dev.yml exec workspace npm install
+    docker compose -f compose.dev.yml exec workspace npm run dev
+    ```
+
+-   **Stopping the environment:**
+
+    To stop the containers, run:
+
+    ```bash
+    docker compose -f compose.dev.yml down
+    ```
+
+## Development with GitHub Codespaces
+
+This repository is configured to use [GitHub Codespaces](https://github.com/features/codespaces) for a cloud-based development environment.
+
+### Getting Started
+
+1.  Click the "Code" button on the repository's main page.
+2.  Select the "Codespaces" tab.
+3.  Click "Create codespace on main".
+
+GitHub will then create a new Codespace and set up the environment for you automatically. This includes:
+- Building the Docker containers for the application, database, and Redis.
+- Installing all Composer dependencies.
+- Creating the `.env` file.
+- Generating the application key.
+- Running database migrations and seeding it with sample data.
+
+### Usage
+
+-   **Accessing the application:**
+    Once the Codespace is ready, it will automatically forward the application's port (8000). You can access the application from the "Ports" tab in the VS Code editor or by clicking the notification that appears.
+
+-   **Running Artisan commands:**
+    You can run `artisan` commands directly in the VS Code terminal:
+    ```bash
+    php artisan route:list
+    ```
+
+-   **Running NPM commands:**
+    You can also run `npm` commands in the terminal:
+    ```bash
+    npm install
+    npm run dev
+    ```

app/Console/Commands/AddAttribute.php

@@ -2,13 +2,13 @@
 
 namespace App\Console\Commands;
 
-use Illuminate\Console\Command;
 use App\Models\LexicalEntry;
-use App\Models\Attribute;
+use Illuminate\Console\Command;
 
 class AddAttribute extends Command
 {
     protected $signature = 'ote:add-attribute {entry_id} {key} {value}';
+
     protected $description = 'Adds an attribute to a lexical entry.';
 
     public function handle()
@@ -19,8 +19,9 @@ public function handle()
 
         $entry = LexicalEntry::find($entryId);
 
-        if (!$entry) {
+        if (! $entry) {
             $this->error("Lexical entry with ID {$entryId} not found.");
+
             return Command::FAILURE;
         }
 

app/Console/Commands/AddEntry.php

@@ -2,14 +2,15 @@
 
 namespace App\Console\Commands;
 
-use Illuminate\Console\Command;
-use App\Models\Token;
 use App\Models\Language;
 use App\Models\LexicalEntry;
+use App\Models\Token;
+use Illuminate\Console\Command;
 
 class AddEntry extends Command
 {
     protected $signature = 'ote:add-entry {token} {language}';
+
     protected $description = 'Creates a new lexical entry linking a token and a language.';
 
     public function handle()
@@ -20,13 +21,15 @@ public function handle()
         $token = Token::where('text', $tokenText)->first();
         $language = Language::where('code', $langCode)->first();
 
-        if (!$token) {
+        if (! $token) {
             $this->error("Token '{$tokenText}' not found. Please add it first.");
+
             return Command::FAILURE;
         }
 
-        if (!$language) {
+        if (! $language) {
             $this->error("Language '{$langCode}' not found. Please add it first.");
+
             return Command::FAILURE;
         }
 

app/Console/Commands/AddLanguage.php

@@ -2,12 +2,13 @@
 
 namespace App\Console\Commands;
 
-use Illuminate\Console\Command;
 use App\Models\Language;
+use Illuminate\Console\Command;
 
 class AddLanguage extends Command
 {
     protected $signature = 'ote:add-language {code} {name}';
+
     protected $description = 'Adds a new language to the lexicon.';
 
     public function handle()
@@ -19,7 +20,7 @@ public function handle()
             $language = Language::create(['code' => $code, 'name' => $name]);
             $this->info("Language '{$name}' ({$code}) added successfully with ID {$language->id}.");
         } catch (\Exception $e) {
-            $this->error("Failed to add language: A language with this code may already exist.");
+            $this->error('Failed to add language: A language with this code may already exist.');
         }
     }
 }