action-server-install/README.md

# Server Install Action

A GitHub 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)
- ✅ Support for multiple Node.js package managers (npm, yarn, pnpm)
- ✅ Automatic dependency installation (npm, composer)
- ✅ Environment file configuration
- ✅ 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@v2
        with:
          install-node: 'true'
          node-version: '20'
          package-manager: 'npm'
      
      - 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@v2
        with:
          install-php: 'true'
          php-version: '8.2'
      
      - 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@v2
        with:
          install-node: 'true'
          install-php: 'true'
          install-nginx: 'true'
          node-version: '20'
          php-version: '8.2'
      
      - name: Run integration tests
        run: |
          cd server
          npm run test:integration
```

### With Custom nginx Configuration

```yaml
- name: Install Server with nginx
  uses: Nodarx/action-server-install@v2
  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: Create environment file
        run: |
          echo "DATABASE_URL=${{ secrets.DATABASE_URL }}" > .env.production
          echo "API_KEY=${{ secrets.API_KEY }}" >> .env.production
      
      - name: Install Server
        uses: Nodarx/action-server-install@v2
        with:
          server-path: './server'
          install-node: 'true'
          install-php: 'true'
          install-nginx: 'true'
          node-version: '20'
          package-manager: 'pnpm'
          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'
          env-file: '.env.production'
          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 | `''` |
| `env-file` | Path to environment file to copy (.env) | 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 | `20` |
| `package-manager` | Package manager for Node.js (npm, yarn, pnpm) | No | `npm` |

### PHP Configuration

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `php-version` | PHP version to use | No | `8.2` |
| `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 | `''` |

## 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) |

## Component Details

### Server Repository
- Clones from: `https://git.ktrix.dev/Nodarx/server`
- Includes recursive submodule initialization
- Updates existing directory if already present

### Node.js
- Uses `actions/setup-node@v4` for Node.js setup
- **npm**: Uses `npm ci` (with fallback to `npm install`)
- **yarn**: Uses `yarn install --frozen-lockfile` (with fallback)
- **pnpm**: Uses `pnpm install --frozen-lockfile` (with fallback, requires `pnpm/action-setup`)
- Default version: Node.js 20 (LTS)

### PHP
- Uses `shivammathur/setup-php@v2` for PHP setup
- Default version: PHP 8.2
- Default extensions: mbstring, xml, ctype, json, curl, zip
- **composer**: Uses `composer install --no-dev --optimize-autoloader`
- Skips gracefully if no `composer.json` found

### nginx
- Installs via system package manager (`apt-get`)
- Supports optional custom configuration file
- Automatically starts the nginx service
- Validates configuration before reload

## Best Practices

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

2. **Pin to specific versions**: Use commit SHA or version tag
   ```yaml
   uses: Nodarx/action-server-install@v2.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@v2
     with:
       install-node: 'true'
   ```

4. **Secure secrets**: Use GitHub Secrets for sensitive variables
   ```yaml
   - name: Create .env file
     run: |
       echo "API_KEY=${{ secrets.API_KEY }}" > .env.production
   
   - uses: Nodarx/action-server-install@v2
     with:
       install-node: 'true'
       env-file: '.env.production'
   ```

5. **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'
   ```

## Development

### Local Testing

To test this action locally, you can use [act](https://github.com/nektos/act):

```bash
act -j test -W .github/workflows/test.yml
```

### Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Versioning

This action follows [Semantic Versioning](https://semver.org/). For the versions available, see the [tags on this repository](../../tags).

### Major Version Tags

Major version tags (v1, v2, etc.) are maintained to point to the latest minor/patch release within that major version:

```yaml
uses: Nodarx/action-server-install@v1  # always latest v1.x.x
uses: Nodarx/action-server-install@v1.2  # always latest v1.2.x
uses: Nodarx/action-server-install@v1.2.3  # exact version
```

## License

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

## Support

If you encounter any issues or have questions:
- Open an [issue](../../issues)
- Check [existing discussions](../../discussions)

## Acknowledgments

- Inspired by GitHub's official actions
- Built with the GitHub Actions community