Deploying OliveTin

Introduction

OliveTin is a web interface for running predefined shell commands and scripts. It provides a simple, clean dashboard with buttons that trigger scripts, making system administration tasks accessible to users who might not be comfortable with the command line.

Built with Go, OliveTin is lightweight, fast, and secure. It’s perfect for creating self-service portals where users can run specific operations without needing SSH access or command-line knowledge. Each action is explicitly defined in a configuration file, ensuring only authorized commands can be executed.

Key highlights of OliveTin:

Simple Interface: Clean, button-based dashboard
Predefined Actions: Only configured commands can run
Arguments Support: Accept user input for commands
Output Display: Show command results in the UI
Access Control: Authentication and authorization options
API Access: REST API for programmatic triggering
Themes: Customizable appearance
Logging: Track all executed commands
Webhooks: Trigger actions via webhooks
Cross-Platform: Runs on Linux, Windows, macOS
Open Source: Apache 2.0 license

This guide walks through deploying OliveTin on Klutch.sh using Docker.

Why Deploy OliveTin on Klutch.sh

Deploying OliveTin on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the Go application deployment automatically.

Persistent Storage: Attach persistent volumes for configuration and logs.

HTTPS by Default: Automatic SSL certificates for secure access.

GitHub Integration: Version-controlled deployments through your repository.

Scalable Resources: Allocate CPU and memory as needed.

Custom Domains: Use your own domain for your operations portal.

Always-On Availability: Your automation portal remains accessible 24/7.

Prerequisites

Before deploying OliveTin on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Understanding of shell commands and scripting
(Optional) A custom domain for your OliveTin instance

Understanding OliveTin Architecture

OliveTin has a simple architecture:

Go Server: Handles web interface and command execution.

YAML Configuration: Defines all available actions.

Web Interface: Button-based dashboard for users.

Execution Engine: Runs shell commands securely.

Logging System: Records all command executions.

Deploying OliveTin on Klutch.sh

Create Your GitHub Repository

Create a new GitHub repository for your OliveTin deployment configuration.

Create Configuration File

Create config.yaml with your actions:

actions:
  - title: Check System Status
    icon: "&#128187;"
    shell: uptime

  - title: View Disk Usage
    icon: "&#128190;"
    shell: df -h

  - title: Check Memory
    icon: "&#129504;"
    shell: free -m

  - title: Run Custom Script
    icon: "&#9881;"
    shell: /scripts/my-script.sh {{ message }}
    arguments:
      - name: message
        title: Enter a message
        type: ascii

Create the Dockerfile

Create a Dockerfile in your repository root:

FROM jamesread/olivetin:latest

# Copy configuration
COPY config.yaml /config/config.yaml

# Create scripts directory
RUN mkdir -p /scripts

# Copy custom scripts (if any)
COPY scripts/ /scripts/
RUN chmod +x /scripts/*

EXPOSE 1337

CMD ["/usr/bin/OliveTin"]

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 1337

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
`/config`	1 GB	Configuration files
`/var/log/OliveTin`	5 GB	Execution logs

Deploy Your Application

Click Deploy to start the build process.

Access OliveTin

Once deployed, access your dashboard at https://your-app.klutch.sh.

Configuration Examples

Basic Actions

Simple command buttons:

actions:
  - title: Hello World
    shell: echo "Hello, World!"

  - title: Current Date
    shell: date

  - title: Hostname
    shell: hostname

Actions with Arguments

Accept user input:

actions:
  - title: Ping Host
    icon: "&#128225;"
    shell: ping -c 4 {{ host }}
    arguments:
      - name: host
        title: Hostname or IP
        type: ascii

  - title: Create User
    shell: useradd {{ username }}
    arguments:
      - name: username
        title: Username
        type: ascii_identifier

Provide predefined choices:

actions:
  - title: Restart Service
    shell: systemctl restart {{ service }}
    arguments:
      - name: service
        title: Select Service
        type: ascii
        choices:
          - nginx
          - apache2
          - mysql

Dangerous Actions

Require confirmation:

actions:
  - title: Clear Cache
    shell: rm -rf /var/cache/*
    popupOnStart: confirm
    timeout: 60

Advanced Configuration

Icons

Use emoji or custom icons:

actions:
  - title: Start Server
    icon: "&#9654;"  # Play button
    shell: ./start.sh

  - title: Stop Server
    icon: "&#9632;"  # Stop button
    shell: ./stop.sh

Timeouts

Set execution limits:

actions:
  - title: Long Running Task
    shell: ./long-task.sh
    timeout: 300  # 5 minutes

Security Configuration

Access Control

Add authentication:

# In config.yaml
authenticationEnabled: true
users:
  - username: admin
    password: $2y$... # bcrypt hash

Limiting Access

Restrict by action:

actions:
  - title: Admin Only Action
    shell: ./admin-task.sh
    acl:
      - "admin"

Logging

Track all executions:

logLevel: "INFO"
logFormat: "json"

API Usage

REST API

Trigger actions programmatically:

curl -X POST https://your-olivetin.klutch.sh/api/StartAction \
  -H "Content-Type: application/json" \
  -d '{"actionName": "Check System Status"}'

Webhooks

Configure webhook triggers:

actions:
  - title: Deploy Application
    shell: ./deploy.sh
    execOnWebhook: true
    webhookId: "deploy-webhook"

Use Cases

Server Management

Common sysadmin tasks:

actions:
  - title: View Logs
    shell: tail -100 /var/log/syslog

  - title: Clear Temp Files
    shell: rm -rf /tmp/*
    popupOnStart: confirm

Application Deployment

Deployment automation:

actions:
  - title: Deploy to Staging
    shell: ./deploy.sh staging

  - title: Deploy to Production
    shell: ./deploy.sh production
    popupOnStart: confirm

Self-Service Portal

User-friendly operations:

actions:
  - title: Reset My Password
    shell: ./reset-password.sh {{ email }}
    arguments:
      - name: email
        title: Your Email
        type: ascii

Production Best Practices

Security Recommendations

Enable authentication
Use bcrypt for passwords
Limit command scope
Review all actions carefully
Log all executions

Command Safety

Write safe scripts:

Validate all inputs
Use absolute paths
Set appropriate timeouts
Handle errors gracefully

Monitoring

Track usage:

Review execution logs
Monitor for failures
Set up alerting

Troubleshooting Common Issues

Commands Not Running

Check script permissions
Verify paths are correct
Review execution logs
Test commands manually

Authentication Problems

Verify password hashes
Check configuration syntax
Review access logs

Timeout Issues

Increase timeout value
Optimize long-running scripts
Consider async execution

Additional Resources

Conclusion

Deploying OliveTin on Klutch.sh provides a secure, user-friendly way to expose shell commands through a web interface. By defining exactly which commands can be run, OliveTin strikes a balance between accessibility and security. Whether for team self-service, customer portals, or personal automation, OliveTin simplifies running predefined operations without requiring command-line expertise.