# Container Installation

> **⚠️ Important Notice: Container Support Disclaimer**
>
> Container support is currently experimental, especially for minimal images, due to limitations in capabilities required to run services. We are actively investigating solutions to improve container support. Some features may not work as expected in containerized environments.

This guide covers installing and configuring the LinuxGuard agent in containerized environments. The agent can be installed in containers using the same package repositories as traditional installations.

## Overview

The LinuxGuard agent can be installed in containers using standard package managers. The installation process is similar to traditional installations, but there are some container-specific considerations:

* **Persistence**: Agent configuration and state need to be persisted across container restarts
* **Volumes**: Mount volumes for configuration and logs
* **Networking**: Ensure the container has network access to `api.linuxguard.io`
* **Base Images**: Use base images that match supported distributions (Debian, RedHat, Alpine)

## Installation Methods

### Method 1: Install in Dockerfile

You can install the LinuxGuard agent directly in your Dockerfile. This approach is recommended for custom images where you want the agent pre-installed.

**Debian/Ubuntu-based Containers:**

```dockerfile
FROM debian:bookworm

# Install prerequisites
RUN apt-get update && apt-get install -y curl

# Install LinuxGuard agent (unified installer)
RUN curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes

# Create directories for agent state and logs
RUN mkdir -p /var/lib/linuxguard /var/log/linuxguard

# Your application setup continues here...
```

**RedHat/CentOS-based Containers:**

```dockerfile
FROM centos:8

# Install prerequisites
RUN yum install -y curl

# Install LinuxGuard agent (unified installer)
RUN curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes

# Create directories for agent state and logs
RUN mkdir -p /var/lib/linuxguard /var/log/linuxguard

# Your application setup continues here...
```

**Alpine-based Containers:**

> **Note**: Alpine and other minimal images have experimental support due to limited container capabilities. We are actively working on improving support for minimal container images.

```dockerfile
FROM alpine:latest

# Install prerequisites
RUN apk add --no-cache curl bash

# Install LinuxGuard agent (unified installer)
RUN curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes

# Create directories for agent state and logs
RUN mkdir -p /var/lib/linuxguard /var/log/linuxguard

# Your application setup continues here...
```

### Method 2: Install at Runtime

You can also install the agent when the container starts. This is useful for dynamic deployments or when you want to keep base images minimal.

> **Note**: Minimal base images have experimental support due to limited container capabilities required to run services. We are actively working on improving support for these environments.

**Using an Entrypoint Script:**

Create an entrypoint script that installs and configures the agent:

```bash
#!/bin/bash
set -e

# Install agent if not present
if ! command -v linuxguard-agent &> /dev/null; then
    curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes
fi

# Enroll agent if not already enrolled
if [ ! -f /var/lib/linuxguard/enrolled ]; then
    linuxguard-agent enroll --api-key="${LINUXGUARD_API_KEY}" --tenant-id="${LINUXGUARD_TENANT_ID}"
    touch /var/lib/linuxguard/enrolled
fi

# Start your application
exec "$@"
```

## Container Configuration

### Environment Variables

Use environment variables to pass credentials to the container:

```bash
LINUXGUARD_API_KEY=ak_1234567890abcdef
LINUXGUARD_TENANT_ID=tenant_abc123xyz
```

### Persistent Volumes

Mount volumes to persist agent state and logs across container restarts:

```yaml
# Docker Compose example
services:
  myapp:
    image: myapp:latest
    volumes:
      - linuxguard-data:/var/lib/linuxguard
      - linuxguard-logs:/var/log/linuxguard
    environment:
      - LINUXGUARD_API_KEY=${LINUXGUARD_API_KEY}
      - LINUXGUARD_TENANT_ID=${LINUXGUARD_TENANT_ID}

volumes:
  linuxguard-data:
  linuxguard-logs:
```

Or with Docker run:

```bash
docker run -d \
  -v linuxguard-data:/var/lib/linuxguard \
  -v linuxguard-logs:/var/log/linuxguard \
  -e LINUXGUARD_API_KEY=ak_1234567890abcdef \
  -e LINUXGUARD_TENANT_ID=tenant_abc123xyz \
  myapp:latest
```

### Kubernetes Deployment

For Kubernetes deployments, use ConfigMaps and Secrets:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: linuxguard-credentials
type: Opaque
stringData:
  api-key: ak_1234567890abcdef
  tenant-id: tenant_abc123xyz
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: myapp
        image: myapp:latest
        env:
        - name: LINUXGUARD_API_KEY
          valueFrom:
            secretKeyRef:
              name: linuxguard-credentials
              key: api-key
        - name: LINUXGUARD_TENANT_ID
          valueFrom:
            secretKeyRef:
              name: linuxguard-credentials
              key: tenant-id
        volumeMounts:
        - name: linuxguard-data
          mountPath: /var/lib/linuxguard
        - name: linuxguard-logs
          mountPath: /var/log/linuxguard
      volumes:
      - name: linuxguard-data
        emptyDir: {}
      - name: linuxguard-logs
        emptyDir: {}
```

## Enrollment in Containers

### Automatic Enrollment

The agent can be enrolled automatically when the container starts using environment variables:

```bash
# In your entrypoint or startup script
linuxguard-agent enroll --api-key="${LINUXGUARD_API_KEY}" --tenant-id="${LINUXGUARD_TENANT_ID}"
```

### Manual Enrollment

You can also enroll manually by executing the command in a running container:

```bash
# Docker
docker exec -it <container-name> linuxguard-agent enroll --api-key=<API_KEY> --tenant-id=<TENANT_ID>

# Kubernetes
kubectl exec -it <pod-name> -- linuxguard-agent enroll --api-key=<API_KEY> --tenant-id=<TENANT_ID>
```

### Enrollment Persistence

To avoid re-enrolling on every container restart, check if enrollment already exists:

```bash
#!/bin/bash
if [ ! -f /var/lib/linuxguard/enrolled ]; then
    linuxguard-agent enroll --api-key="${LINUXGUARD_API_KEY}" --tenant-id="${LINUXGUARD_TENANT_ID}"
    if [ $? -eq 0 ]; then
        touch /var/lib/linuxguard/enrolled
    fi
fi
```

## Container-Specific Considerations

### Running as Non-Root

If your container runs as a non-root user, you may need to adjust permissions or use sudo:

```dockerfile
# Allow non-root user to run agent commands
RUN chmod +s /usr/bin/linuxguard-agent
```

Or use sudo in your startup script:

```bash
sudo linuxguard-agent enroll --api-key="${LINUXGUARD_API_KEY}" --tenant-id="${LINUXGUARD_TENANT_ID}"
```

### Log Access

Access logs from outside the container:

```bash
# Docker
docker exec <container-name> tail -f /var/log/linuxguard/agent.log

# Kubernetes
kubectl exec <pod-name> -- tail -f /var/log/linuxguard/agent.log
```

### Network Requirements

Ensure your container has outbound HTTPS access to:

* `api.linuxguard.io` (port 443)
* `packages.linuxguard.io` (port 443, for installation)

### Resource Limits

The agent requires minimal resources:

* **CPU**: 0.1 cores recommended
* **Memory**: 50-100 MB
* **Disk**: 100-500 MB for logs and state

## Verification

After installation and enrollment, verify the agent is working:

```bash
# Check agent status
docker exec <container-name> linuxguard-agent status

# Check logs
docker exec <container-name> tail -n 50 /var/log/linuxguard/agent.log

# Verify enrollment
docker exec <container-name> test -f /var/lib/linuxguard/enrolled && echo "Enrolled" || echo "Not enrolled"
```

## Troubleshooting

Common container-specific issues:

1. **Agent not persisting**: Ensure volumes are mounted for `/var/lib/linuxguard`
2. **Enrollment fails**: Check network connectivity and environment variables
3. **Permission errors**: Verify user permissions or use sudo
4. **Logs not accessible**: Check volume mounts and file permissions

For more troubleshooting help, see the [Troubleshooting Guide](/troubleshooting.md).

***

**Next Step**: [Configuration →](/how-to-guides/how-to/configuration.md)

**Related**: [Installation Overview](/how-to-guides/how-to/installation.md) | [Alpine Installation](/how-to-guides/how-to/installation/alpine.md) | [Troubleshooting](/troubleshooting.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.linuxguard.io/how-to-guides/how-to/installation/container-installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.