# ObjectStore Publisher Documentation

## Setting up your S3 Bucket

Follow these steps to set up and configure your S3 bucket:

### Prerequisites
1. Obtain your S3 access key ID and secret from your S3 object store administrator
2. Install AWS CLI
3. Configure AWS CLI:
   aws configure

   Enter your AWS ID, secret, region, and output format (for EC S3 like s3-lux.obj.cec.eu.int, use region "lux")

### Certificate Handling (For EC/Custom S3 Services)
When using a private or corporate S3 service:

1. Identify which root certificate is in use by opening the HTTPS URL in browser and viewing the certificate info
2. Export the relevant root certificate in PEM format:
   - On Windows: Open Computer Certificates Manager
   - Navigate to Trusted Root Certification Authorities → Certificates
   - Find the root certificate in use
   - Export as DER encoded binary (.cer format)
   - Convert to PEM format: `openssl x509 -inform der -in yourfile.cer -out yourfile.pem`

3. Include this certificate in your configuration:

   const ObjectStoreRootCert = [
     fs.readFileSync("./apps/my-workplace-e2e-wd/cert/ecrootca2.pem")
   ];

4. Set the root certificate for AWS CLI:
   export AWS_CA_BUNDLE="/path/to/your/certificate.pem"

### Creating and Managing Buckets

Create a bucket:

aws --endpoint="https://s3-lux.obj.cec.eu.int" s3 mb s3://your-bucket-name

View existing buckets:

aws --endpoint="https://s3-lux.obj.cec.eu.int" s3 ls

Delete a bucket:

aws --endpoint="https://s3-lux.obj.cec.eu.int" s3 rb s3://your-bucket-name

### Making Bucket Content Publicly Accessible

Configure the bucket to allow public access:

aws s3api put-public-access-block --endpoint="https://s3-lux.obj.cec.eu.int" --bucket your-bucket-name --public-access-block-configuration "BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false"

## Connecting to Different S3 Environments

### AWS Public S3
For connecting to standard AWS S3:

s3ClientConfig: {
  endpoint: "https://s3.eu-west-3.amazonaws.com",
  region: "eu-west-3",
  signatureVersion: "v4",
  useProxy: true // If needed
}

### EC/Custom S3 Infrastructure
For connecting to an EC or private S3 instance:

s3ClientConfig: {
  endpoint: "https://s3-lux.obj.cec.eu.int", // Your custom S3 endpoint
  region: "lux", // Custom region identifier
  signatureVersion: "v4",
  httpOptions: {ca: ObjectStoreRootCert} // Custom certificate if needed
}

## ObjectStorePublisher Configuration

### AWS S3 Configuration Example
{
  type: ObjectStorePublisher,
  config: {
    publish: 'always', // never, fail or always
    s3ClientConfig: {
      endpoint: "https://s3.eu-west-3.amazonaws.com",
      region: "eu-west-3",
      signatureVersion: "v4",
      useProxy: true // If needed
      },
    dirPath: "allure-report",
    s3Bucket: "your-bucket-name",
    s3rootKey: "-e2e-test-report",
    prefixRootKeyWithTime: true,
    acl: "public-read",
    indexFile: "index.html"
  }
}

# EC/Custom S3 Configuration Example
{
  type: ObjectStorePublisher,
  config: {
    publish: 'always',
    s3ClientConfig: {
      endpoint: "https://s3-lux.obj.cec.eu.int", // EC S3 endpoint
      region: "lux", // EC region
      signatureVersion: "v4",
      httpOptions: {ca: ObjectStoreRootCert} // EC certificate
    },
    dirPath: "allure-report-e2e",
    s3Bucket: "e2e-test-results",
    s3rootKey: "-e2e-trial-report",
    prefixRootKeyWithTime: true,
    acl: "public-read",
    indexFile: "index.html"
  }
}

### Configuration with IAM Role Assumption
If you need to assume an IAM role for S3 access:

{
  type: ObjectStorePublisher,
  config: {
    publish: 'always',
    s3ClientConfig: {
      endpoint: "https://s3.eu-west-3.amazonaws.com",
      region: "eu-west-3",
      signatureVersion: "v4",
      assumeRole: true // Enable role assumption
    },
    dirPath: "allure-report",
    s3Bucket: "your-bucket-name",
    s3rootKey: "-e2e-test-report",
    prefixRootKeyWithTime: true,
    indexFile: "index.html"
    // Note: ACL is not required and generally should be omitted when using assumed roles
  }
}

The publisher will automatically use the role ARN from the AWS_ASSUME_ROLE environment variable.
Make sure to set this environment variable before running:

```bash
export AWS_ASSUME_ROLE=arn:aws:iam::123456789012:role/YourRoleName
```

### Configuration with Proxy Support
If you need to use a proxy to connect to S3:

{
  type: ObjectStorePublisher,
  config: {
    publish: 'always',
    s3ClientConfig: {
      endpoint: "https://s3.eu-west-3.amazonaws.com", // Or your custom endpoint
      region: "eu-west-3", // Or your custom region
      signatureVersion: "v4",
      useProxy: true // Enable proxy support
    },
  / / Other settings as above
  }
}

The publisher will automatically use the proxy settings from environment variables:
- `HTTP_PROXY` or `http_proxy`
- `HTTPS_PROXY` or `https_proxy`
- `NO_PROXY` or `no_proxy`

Example of setting proxy environment variables:

bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

## Important Notes

1. **Endpoint URL Format**: 
   - For AWS S3: Use the API endpoint format (`s3.region.amazonaws.com`)
   - For EC/custom S3: Use your infrastructure's endpoint (e.g., `s3-lux.obj.cec.eu.int`)

2. **ACL Settings**: The `acl: "public-read"` setting makes uploaded files publicly accessible. Remove this setting if you want the files to remain private.

3. **Authentication**: Ensure your environment has the AWS authentication variables set:
   ```bash
   export AWS_ACCESS_KEY_ID=your_access_key
   export AWS_SECRET_ACCESS_KEY=your_secret_key
   ```

4. **Proxy Configuration**: When using `useProxy: true`, the service automatically detects and uses proxy settings from environment variables.

## Using Vault for Credentials

Instead of manually exporting AWS credentials, you can use the `vaultEnvVars` configuration in your wdio.conf.js file to automatically retrieve secrets from vault and set them as environment variables:

```javascript
// Example from wdio.conf.js
vaultConfig: {
  endpoint: 'https://your-vault-endpoint.com/v1',
  user: vaultUser,
  password: vaultPassword,
  namespace: '/YOUR/NAMESPACE',
  testusersPath: '/path/to/users/'
},
// vaultEnvVars takes all entries of the given vault secret and adds them as environment variables
vaultEnvVars: {
  s3: {
    path: "/path/to/objectstore/secret",
    key: "default"
  },
},
```

With this configuration:
1. The system will retrieve the secret from the specified vault path and key
2. For each property in the secret, an environment variable will be created
3. This happens automatically before the tests run, so your S3 publisher will have the required AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables set

This approach is recommended for CI/CD pipelines and environments where you don't want to manually manage credentials.