action-server-install/README.md

# Server Install Action

A action to clone the Nodarx server repository and install Node.js, PHP, and/or nginx based on test requirements. Perfect for creating lean test environments (e.g., JS tests install only Node) while supporting full integration tests with all components.

## Features

- ✅ Clone Nodarx server repository with submodule support
- ✅ Flexible component installation (Node.js, PHP, nginx)
- ✅ Automatic dependency installation (npm, composer)
- ✅ Custom build commands
- ✅ Post-installation scripts
- ✅ Comprehensive error handling and logging

## Usage

### Node.js Only (Unit Tests)

```yaml
name: Node.js Unit Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install Server with Node.js
        uses: Nodarx/action-server-install@v1
        with:
          install-node: 'true'
          node-version: '24'
      
      - name: Run tests
        run: |
          cd server
          npm test
```

### PHP Only (Unit Tests)

```yaml
name: PHP Unit Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install Server with PHP
        uses: Nodarx/action-server-install@v1
        with:
          install-php: 'true'
          php-version: '8.5'
      
      - name: Run tests
        run: |
          cd server
          ./vendor/bin/phpunit
```

### Full Integration Test (All Components)

```yaml
name: Integration Tests
on: [push]

jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - name: Install Server with All Components
        uses: Nodarx/action-server-install@v1
        with:
          install-node: 'true'
          install-php: 'true'
          install-nginx: 'true'
          node-version: '24'
          php-version: '8.5'
      
      - name: Run integration tests
        run: |
          cd server
          npm run test:integration
```

### With Database Configuration

Point the checked-out server at a database (e.g. a `mongo` service container) and write the value into `config/system.php` before dependencies or base modules are installed:

```yaml
services:
  mongo:
    image: mongo:7
    ports:
      - 27017:27017

steps:
  - name: Install server with database configuration
    uses: Nodarx/action-server-install@v1
    with:
      install-php: 'true'
      database-uri: 'mongodb://127.0.0.1:27017/?tls=false'
      database-name: 'ktrix_ci'
      app-environment: 'test'
```

Any override left blank keeps the value already committed in `config/system.php`.

### With Base Modules (Password Authentication)

`install-base-modules` clones the password authentication provider module (from `base-modules-repository`, via [action-module-install](https://git.ktrix.dev/Nodarx/action-module-install)), then installs and enables it with `bin/console`. This requires PHP and a reachable, configured database:

```yaml
services:
  mongo:
    image: mongo:7
    ports:
      - 27017:27017

steps:
  - name: Install server with base modules
    uses: Nodarx/action-server-install@v1
    with:
      install-php: 'true'
      database-uri: 'mongodb://127.0.0.1:27017/?tls=false'
      database-name: 'ktrix_ci'
      install-base-modules: 'true'

  - name: Provision a tenant and user for testing
    run: |
      cd server
      php bin/console tenant:create ci.test --identifier ci
      php bin/console user:create ci tester@ci.test
      php bin/console user:password ci tester@ci.test 'Sup3r-Secret!'
```

### With Custom nginx Configuration

```yaml
- name: Install Server with nginx
  uses: Nodarx/action-server-install@v1
  with:
    install-nginx: 'true'
    nginx-config: './config/nginx.conf'
```

### Advanced Example with All Options

```yaml
name: Deploy Server
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Server
        uses: Nodarx/action-server-install@v1
        with:
          server-path: './server'
          install-node: 'true'
          install-php: 'true'
          install-nginx: 'true'
          node-version: '20'
          php-version: '8.2'
          php-extensions: 'mbstring, xml, ctype, json, curl, zip, pdo, pdo_mysql'
          nginx-config: './config/nginx.conf'
          install-dependencies: 'true'
          build-command: 'npm run build'
          post-install-script: './scripts/post-install.sh'
```

## Inputs

### Component Selection

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `install-node` | Install Node.js environment | No | `false` |
| `install-php` | Install PHP environment | No | `false` |
| `install-nginx` | Install nginx web server | No | `false` |

**Note:** At least one component must be enabled.

### General Configuration

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `server-path` | Path where the server will be cloned/installed | No | `./server` |
| `install-dependencies` | Whether to install dependencies (npm/composer) | No | `true` |
| `build-command` | Custom build command to run after install | No | `''` |
| `post-install-script` | Custom script to run after installation | No | `''` |

### Node.js Configuration

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `node-version` | Node.js version to use | No | `24` |


### PHP Configuration

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `php-version` | PHP version to use | No | `8.5` |
| `php-extensions` | Comma-separated list of PHP extensions to install | No | `mbstring, xml, ctype, json, curl, zip` |

### nginx Configuration

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `nginx-config` | Path to nginx configuration file | No | `''` |

### Server Settings Configuration

Overrides are written into the checked-out `config/system.php`. Requires `install-php: 'true'`; any input left blank keeps the repository's committed default.

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `database-uri` | MongoDB connection URI | No | `''` |
| `database-name` | MongoDB database name | No | `''` |
| `app-environment` | Application environment, e.g. `test` | No | `''` |
| `security-salt` | Security salt | No | `''` |

### Base Modules

Clones the configured module repository directly, then installs and enables the
module via `bin/console`. This avoids a nested remote-action dependency, so the
action works on GitHub-compatible hosts without resolving
`Nodarx/action-module-install` through GitHub. Requires `install-php` and a
reachable, configured database.

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `install-base-modules` | Clone, install, and enable the base module set (currently: `authentication_provider_password`) | No | `false` |
| `base-modules-repository` | Repository URL for the password authentication provider module | No | `https://git.ktrix.dev/Nodarx/authentication_provider_password` |
| `base-modules-branch` | Branch, tag, or commit to check out for the password authentication provider module | No | `main` |

## Testing Against Another Source

The action's test workflow keeps its server fixture source in repository
variables. The defaults target `Nodarx/server` on `https://git.ktrix.dev`.
To test another source without editing the workflow, set:

| Repository variable | Purpose | Default |
|---------------------|---------|---------|
| `TEST_SERVER_REPOSITORY` | Repository in `owner/name` form | `Nodarx/server` |
| `TEST_SERVER_REF` | Branch, tag, or commit | `main` |
| `TEST_GIT_SERVER_URL` | Base URL of the GitHub-compatible server | `https://git.ktrix.dev` |

For a private source, also add a repository secret named
`TEST_SERVER_TOKEN`. Public repositories do not require the secret.

## Outputs

| Output | Description |
|--------|-------------|
| `install-status` | Status of the installation (success/failure) |
| `install-path` | Path where the server was installed |
| `node-installed` | Whether Node.js was installed (true/false) |
| `php-installed` | Whether PHP was installed (true/false) |
| `nginx-installed` | Whether nginx was installed (true/false) |
| `base-modules-installed` | Whether the base module set was installed (true/false) |

## Best Practices

1. **Enable only needed components**: For faster test runs
   ```yaml
   # JS unit tests - Node.js only
   - uses: Nodarx/action-server-install@v1
     with:
       install-node: 'true'
   ```

2. **Pin to specific versions**: Use commit SHA or version tag
   ```yaml
   uses: Nodarx/action-server-install@v1.0.0
   ```

3. **Cache dependencies**: Combine with caching for faster builds
   ```yaml
   - uses: actions/cache@v4
     with:
       path: ~/.npm
       key: ${{ runner.os }}-node-${{ hashFiles('server/package-lock.json') }}
   
   - uses: Nodarx/action-server-install@v1
     with:
       install-node: 'true'
   ```

4. **Test different component combinations**: Matrix testing
   ```yaml
   strategy:
     matrix:
       include:
         - name: Node Tests
           install-node: 'true'
           install-php: 'false'
         - name: PHP Tests
           install-node: 'false'
           install-php: 'true'
         - name: Integration Tests
           install-node: 'true'
           install-php: 'true'
   ```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.