docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
22
ansible/kernos/.env.j2
Normal file
22
ansible/kernos/.env.j2
Normal file
@@ -0,0 +1,22 @@
|
||||
# Kernos Environment Configuration
|
||||
# HTTP-enabled MCP shell server using FastMCP
|
||||
|
||||
# ============================================================================
|
||||
# Server Configuration
|
||||
# ============================================================================
|
||||
HOST={{ kernos_host | default('0.0.0.0') }}
|
||||
PORT={{ kernos_port }}
|
||||
|
||||
# ============================================================================
|
||||
# Logging Configuration
|
||||
# ============================================================================
|
||||
LOG_FORMAT={{ kernos_log_format | default('json') }}
|
||||
LOG_LEVEL={{ kernos_log_level | default('INFO') }}
|
||||
ENVIRONMENT={{ kernos_environment | default('production') }}
|
||||
|
||||
# ============================================================================
|
||||
# Security Configuration
|
||||
# ============================================================================
|
||||
# Comma-separated whitelist of allowed commands
|
||||
# Commands after shell operators (;, &&, ||, |) are also validated
|
||||
ALLOW_COMMANDS={{ kernos_allow_commands }}
|
||||
180
ansible/kernos/deploy.yml
Normal file
180
ansible/kernos/deploy.yml
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
- name: Deploy Kernos MCP Shell Server
|
||||
hosts: kernos
|
||||
vars:
|
||||
ansible_common_remote_group: "{{kernos_group}}"
|
||||
allow_world_readable_tmpfiles: true
|
||||
tasks:
|
||||
- name: Create Kernos group
|
||||
become: true
|
||||
ansible.builtin.group:
|
||||
name: "{{kernos_group}}"
|
||||
state: present
|
||||
|
||||
- name: Create kernos user
|
||||
become: true
|
||||
ansible.builtin.user:
|
||||
name: "{{kernos_user}}"
|
||||
group: "{{kernos_group}}"
|
||||
home: "/home/{{kernos_user}}"
|
||||
shell: /bin/bash
|
||||
system: false
|
||||
create_home: true
|
||||
|
||||
- name: Add remote_user to kernos group
|
||||
become: true
|
||||
ansible.builtin.user:
|
||||
name: "{{remote_user}}"
|
||||
groups: "{{kernos_group}}"
|
||||
append: true
|
||||
|
||||
- name: Reset connection to pick up new group membership
|
||||
ansible.builtin.meta: reset_connection
|
||||
|
||||
- name: Create required directories
|
||||
become: true
|
||||
ansible.builtin.file:
|
||||
path: "{{kernos_directory}}"
|
||||
owner: "{{kernos_user}}"
|
||||
group: "{{kernos_group}}"
|
||||
state: directory
|
||||
mode: '750'
|
||||
|
||||
- name: Ensure tar is installed for unarchive task
|
||||
become: true
|
||||
ansible.builtin.apt:
|
||||
name:
|
||||
- tar
|
||||
state: present
|
||||
update_cache: true
|
||||
|
||||
- name: Ensure Python, Python Dev, Venv module is installed
|
||||
become: true
|
||||
ansible.builtin.apt:
|
||||
name: [python3, python3-venv, python3-dev]
|
||||
state: present
|
||||
update_cache: true
|
||||
|
||||
- name: Transfer and unarchive git archive
|
||||
become: true
|
||||
ansible.builtin.unarchive:
|
||||
src: "~/rel/kernos_{{kernos_rel}}.tar"
|
||||
dest: "{{kernos_directory}}"
|
||||
owner: "{{kernos_user}}"
|
||||
group: "{{kernos_group}}"
|
||||
mode: '550'
|
||||
notify: restart kernos
|
||||
|
||||
- name: Ensure venv directory ownership is correct
|
||||
become: true
|
||||
ansible.builtin.file:
|
||||
path: "{{kernos_directory}}/.venv"
|
||||
owner: "{{kernos_user}}"
|
||||
group: "{{kernos_group}}"
|
||||
state: directory
|
||||
recurse: true
|
||||
when: ansible_facts['file'] is defined or true
|
||||
|
||||
- name: Create virtual environment for Kernos
|
||||
become: true
|
||||
become_user: "{{kernos_user}}"
|
||||
ansible.builtin.command:
|
||||
cmd: "python3 -m venv {{kernos_directory}}/.venv/"
|
||||
creates: "{{kernos_directory}}/.venv/bin/activate"
|
||||
|
||||
- name: Install wheel in virtual environment
|
||||
become: true
|
||||
become_user: "{{kernos_user}}"
|
||||
ansible.builtin.pip:
|
||||
name:
|
||||
- wheel
|
||||
state: latest
|
||||
virtualenv: "{{kernos_directory}}/.venv"
|
||||
|
||||
- name: Install pyproject.toml dependencies in virtualenv
|
||||
become: true
|
||||
become_user: "{{kernos_user}}"
|
||||
ansible.builtin.pip:
|
||||
chdir: "{{kernos_directory}}"
|
||||
name: .
|
||||
virtualenv: "{{kernos_directory}}/.venv"
|
||||
virtualenv_command: python3 -m venv
|
||||
notify: restart kernos
|
||||
|
||||
- name: Template Kernos .env configuration
|
||||
become: true
|
||||
ansible.builtin.template:
|
||||
src: .env.j2
|
||||
dest: "{{kernos_directory}}/.env"
|
||||
owner: "{{kernos_user}}"
|
||||
group: "{{kernos_group}}"
|
||||
mode: '640'
|
||||
notify: restart kernos
|
||||
|
||||
- name: Template systemd service file
|
||||
become: true
|
||||
ansible.builtin.template:
|
||||
src: kernos.service.j2
|
||||
dest: /etc/systemd/system/kernos.service
|
||||
owner: root
|
||||
group: root
|
||||
mode: '644'
|
||||
notify: restart kernos
|
||||
|
||||
- name: Enable and start kernos service
|
||||
become: true
|
||||
ansible.builtin.systemd:
|
||||
name: kernos
|
||||
enabled: true
|
||||
state: started
|
||||
daemon_reload: true
|
||||
|
||||
- name: Flush handlers to restart service before validation
|
||||
ansible.builtin.meta: flush_handlers
|
||||
|
||||
- name: Validate Kernos liveness endpoint
|
||||
ansible.builtin.uri:
|
||||
url: "http://localhost:{{kernos_port}}/live"
|
||||
status_code: 200
|
||||
return_content: true
|
||||
register: live_check
|
||||
retries: 5
|
||||
delay: 5
|
||||
until: live_check.status == 200
|
||||
|
||||
- name: Validate Kernos readiness endpoint
|
||||
ansible.builtin.uri:
|
||||
url: "http://localhost:{{kernos_port}}/ready"
|
||||
status_code: 200
|
||||
return_content: true
|
||||
register: ready_check
|
||||
retries: 5
|
||||
delay: 5
|
||||
until: ready_check.status == 200
|
||||
|
||||
- name: Validate Kernos health endpoint
|
||||
ansible.builtin.uri:
|
||||
url: "http://localhost:{{kernos_port}}/health"
|
||||
status_code: 200
|
||||
return_content: true
|
||||
register: health_check
|
||||
retries: 5
|
||||
delay: 5
|
||||
until: health_check.status == 200
|
||||
|
||||
- name: Validate Kernos /metrics endpoint
|
||||
ansible.builtin.uri:
|
||||
url: "http://localhost:{{kernos_port}}/metrics"
|
||||
status_code: 200
|
||||
return_content: false
|
||||
register: metrics_check
|
||||
retries: 5
|
||||
delay: 5
|
||||
until: metrics_check.status == 200
|
||||
|
||||
handlers:
|
||||
- name: restart kernos
|
||||
become: true
|
||||
ansible.builtin.systemd:
|
||||
name: kernos
|
||||
state: restarted
|
||||
23
ansible/kernos/kernos.service
Normal file
23
ansible/kernos/kernos.service
Normal file
@@ -0,0 +1,23 @@
|
||||
[Unit]
|
||||
Description=Kernos MCP Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=nobody
|
||||
Group=nogroup
|
||||
WorkingDirectory=/srv/kernos
|
||||
ExecStart=/srv/kernos/.venv/bin/kernos
|
||||
EnvironmentFile=/srv/kernos/.env
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
# Security hardening
|
||||
NoNewPrivileges=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=read-only
|
||||
PrivateTmp=false
|
||||
ReadWritePaths=/
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
23
ansible/kernos/kernos.service.j2
Normal file
23
ansible/kernos/kernos.service.j2
Normal file
@@ -0,0 +1,23 @@
|
||||
[Unit]
|
||||
Description=Kernos MCP Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User={{kernos_user}}
|
||||
Group={{kernos_group}}
|
||||
WorkingDirectory={{kernos_directory}}
|
||||
ExecStart={{kernos_directory}}/.venv/bin/kernos
|
||||
EnvironmentFile={{kernos_directory}}/.env
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
# Security hardening
|
||||
NoNewPrivileges=false
|
||||
ProtectSystem=false
|
||||
ProtectHome=false
|
||||
PrivateTmp=false
|
||||
ReadWritePaths=/
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
47
ansible/kernos/stage.yml
Normal file
47
ansible/kernos/stage.yml
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
- name: Stage Kernos release tarball
|
||||
hosts: localhost
|
||||
gather_facts: false
|
||||
vars:
|
||||
archive_path: "{{rel_dir}}/kernos_{{kernos_rel}}.tar"
|
||||
kernos_repo_url: "ssh://robert@clio.helu.ca:18677/mnt/dev/kernos"
|
||||
kernos_repo_dir: "{{repo_dir}}/kernos"
|
||||
|
||||
tasks:
|
||||
- name: Ensure release directory exists
|
||||
file:
|
||||
path: "{{rel_dir}}"
|
||||
state: directory
|
||||
mode: '755'
|
||||
|
||||
- name: Ensure repo directory exists
|
||||
file:
|
||||
path: "{{repo_dir}}"
|
||||
state: directory
|
||||
mode: '755'
|
||||
|
||||
- name: Clone Kernos repository if not present
|
||||
ansible.builtin.git:
|
||||
repo: "{{kernos_repo_url}}"
|
||||
dest: "{{kernos_repo_dir}}"
|
||||
version: "{{kernos_rel}}"
|
||||
accept_hostkey: true
|
||||
register: git_clone
|
||||
ignore_errors: true
|
||||
|
||||
- name: Fetch all remote branches and tags
|
||||
ansible.builtin.command: git fetch --all
|
||||
args:
|
||||
chdir: "{{kernos_repo_dir}}"
|
||||
when: git_clone is not changed
|
||||
|
||||
- name: Pull latest changes
|
||||
ansible.builtin.command: git pull
|
||||
args:
|
||||
chdir: "{{kernos_repo_dir}}"
|
||||
when: git_clone is not changed
|
||||
|
||||
- name: Create Kernos archive for specified release
|
||||
ansible.builtin.command: git archive -o "{{archive_path}}" "{{kernos_rel}}"
|
||||
args:
|
||||
chdir: "{{kernos_repo_dir}}"
|
||||
Reference in New Issue
Block a user