Document create environment command

[Copilot]

Adds user-facing documentation for the create environment command, completing the final subissue of epic #34.

Documentation Added

• Command reference (docs/user-guide/commands/create-environment.md):

  • Syntax with all CLI flags and configuration format
  • JSON schema with field validation rules
  • 8 practical examples covering development, CI/CD, and production setups
  • Troubleshooting section for configuration validation, SSH keys, permissions, and parsing errors
  • Workflow integration with template generation and next steps

• Commands index updates (docs/user-guide/commands.md):

  • Mark create environment and create template as ✅ Fully Implemented
  • Update workflow examples to include environment creation
  • Add --working-dir to common options

Example Usage

# Generate and edit configuration template
torrust-tracker-deployer create template config.json
nano config.json  # Replace placeholders

# Create environment
torrust-tracker-deployer create environment --env-file config.json

# With custom working directory
torrust-tracker-deployer create environment \
  --env-file config.json \
  --working-dir /opt/deployments

Configuration format:

{
  "environment": {
    "name": "production"
  },
  "ssh_credentials": {
    "private_key_path": "~/.ssh/id_rsa",
    "public_key_path": "~/.ssh/id_rsa.pub",
    "username": "torrust",
    "port": 22
  }
}

Closes #52

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Subissue 10/10] Document Create Environment Command</issue_title>
<issue_description># Document Create Environment Command

Epic Subissue: 10 of 10
Parent Epic: #34 - Create Environment Command
Related: User Guide Commands, Create Environment Command Documentation

Overview

Add comprehensive user-facing documentation for the create environment command to the user guide. This documentation will help users understand how to create new deployment environments from configuration files.

The create environment command is now fully implemented (Subissues 1-7) and needs proper user-facing documentation in the docs/user-guide/ directory.

Goals

• Create detailed command documentation at docs/user-guide/commands/create-environment.md
• Update docs/user-guide/commands.md to mark create command as implemented
• Include practical examples for common use cases
• Document all command flags and configuration file formats
• Provide troubleshooting guidance for common errors

🏗️ Architecture Requirements

Documentation Type: User Guide
Module Path: docs/user-guide/commands/
Pattern: Command Reference Documentation

Documentation Structure Requirements

• Follow existing command documentation pattern (see docs/user-guide/commands/destroy.md)
• Include command synopsis, description, usage examples, and troubleshooting
• Use clear, actionable language for user-facing documentation
• Provide both JSON and TOML configuration examples

Anti-Patterns to Avoid

• ❌ Developer-focused implementation details in user guide
• ❌ Missing practical examples
• ❌ Unclear error troubleshooting guidance
• ❌ Inconsistent formatting with other command docs

Specifications

Documentation Structure

The command documentation should follow this structure:

1. Command Overview

   • Brief description of what the command does
   • When to use it
   • Implementation status badge

2. Syntax

   • Command signature with all flags
   • Required vs optional parameters

3. Configuration File Format

   • JSON format example
   • TOML format example
   • Field descriptions with validation rules

4. Examples

   • Basic usage (minimal configuration)
   • Advanced usage (custom working directory)
   • Template generation workflow

5. Common Use Cases

   • Development environment setup
   • Testing environment setup
   • Production environment setup

6. Troubleshooting

   • Configuration validation errors
   • File system permission issues
   • Invalid SSH key paths
   • Environment name conflicts

7. Related Commands

   • Link to provision command
   • Link to destroy command
   • Link to template generation

Content to Include

Command Overview Section

# Create Environment Command

**Status**: ✅ Fully Implemented

Create a new deployment environment from a configuration file. This command initializes the environment with validated configuration, SSH credentials, and prepares it for provisioning.

**Use when**:

- Setting up a new deployment environment
- Initializing environment configuration from templates
- Preparing environments for provisioning

**Command**: `torrust-tracker-deployer create environment`

Syntax Section

## Syntax

```bash
torrust-tracker-deployer create environment --env-file <path> [options]
```

Required Flags

• --env-file <path> - Path to environment configuration file (JSON or TOML)

Optional Flags

• --working-dir <path> - Working directory for environment data (default: .)
• --log-output <mode> - Logging output mode: stderr, file, file-and-stderr (default: stderr)

#### Configuration Format Section

```markdown
## Configuration File Format

### JSON Format

```json
{
  "environment": {
    "name": "my-environment"
  },
  "ssh_credentials": {
    "private_key_path": "~/.ssh/id_rsa",
    "public_key_path": "~/.ssh/id_rsa.pub",
    "username": "deployer",
    "port": 22
  }
}

TOML Format

[environment]
name = "my-environment"

[ssh_credentials]
private_key_path = "~/.ssh/id_rsa"
public_key_path = "~/.ssh/id_rsa.pub"
username = "deployer"
port = 22

Field Descriptions

• environment.name (required): Unique environment identifier
  • Must be lowercase alphanumeric with hyphens
  • Used for directory names and resource identification
• ssh_credentials.private_key_path (required): Path to SSH private key
  • Supports ~ for home directory expansion
  • File must exist and be readable
• ssh_credentials.public_key_path (required): Path to SSH public key
  • Supports ~ for home directory expansion...

• Fixes [Subissue 10/10] Document Create Environment Command #52

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[josecelano]

ACK 7fe3690