configure-ubuntu

Ubuntu server configuration via cloud-init and systemd. Use when writing cloud-init YAML, configuring systemd services, setting up nginx, or troubleshooting VM configuration issues.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive guidance and ready-to-use templates for Ubuntu server configuration using cloud-init and systemd. It streamlines the process of VM provisioning, Nginx setup, and service management across major cloud platforms like AWS, Azure, and GCP, while enforcing security best practices and preventing common deployment pitfalls.

Use Cases

  • Automating cloud VM provisioning using standardized cloud-init YAML templates for consistent environment setup.
  • Configuring and troubleshooting systemd service units to ensure reliable application lifecycle management.
  • Deploying Nginx reverse proxies with support for HTTP, self-signed SSL, or automated Let's Encrypt certificate integration.
  • Implementing secure server access patterns including bastion host setup, UFW firewall configuration, and fail2ban integration.
  • Standardizing application environments by managing environment variables, service users, and strict file permission structures.
  • Debugging complex infrastructure issues related to cloud-init execution logs, SSH access, and service permission errors.
nameconfigure-ubuntu
descriptionUbuntu server configuration via cloud-init and systemd. Use when writing cloud-init YAML, configuring systemd services, setting up nginx, or troubleshooting VM configuration issues.

Configure Ubuntu Skill

Purpose

This skill provides guidance for configuring Ubuntu LTS servers via cloud-init automation for any cloud platform (AWS, Azure, GCP, DigitalOcean, etc.).

Note: All examples in this skill currently use Ubuntu 24.04 LTS. Update version-specific package names or paths as needed for other LTS releases.

When to Use This Skill

Use this skill when:

  • Writing cloud-init YAML for VM provisioning
  • Configuring systemd services
  • Setting up nginx reverse proxies
  • Troubleshooting cloud-init or systemd issues
  • Setting file permissions for service users

Reference Selection Guide

Choose the appropriate reference based on your task:

Task Reference File
Complete cloud-init configurations references/examples/*.yaml
Cloud-init syntax and patterns references/cloud-init-patterns.md
systemd service units references/systemd-patterns.md
Debugging failures or errors references/common-pitfalls.md

Ready-to-Use Examples

Example File
SSH bastion host references/examples/bastion.yaml
Nginx reverse proxy (HTTP) references/examples/proxy-http.yaml ← default
Nginx reverse proxy (HTTPS, self-signed) references/examples/proxy-https.yaml
Nginx reverse proxy (HTTPS, Let's Encrypt) references/examples/proxy-https-letsencrypt.yaml
Nginx static file server references/examples/static-files.yaml
Python/Flask server references/examples/flask.yaml
Node.js server references/examples/nodejs.yaml
Java/Spring Boot server references/examples/java.yaml
.NET server references/examples/dotnet.yaml

HTTPS Options:

  • Use proxy-http.yaml by default (no SSL)
  • Use proxy-https.yaml for self-signed certificates (development/internal)
  • Use proxy-https-letsencrypt.yaml for trusted certificates (requires domain name)

When to Read Multiple References

  • New VM setup: Start with relevant example, then cloud-init-patterns.md for customization
  • Service won't start: common-pitfalls.md + systemd-patterns.md
  • SSH access broken: common-pitfalls.md (Issue #1)
  • Permission denied errors: common-pitfalls.md (Issues #4, #5, #6)
  • Scheduled tasks: systemd-patterns.md (Systemd Timers section)
  • Production HTTPS: proxy-https-letsencrypt.yaml (requires domain name)
  • Static website: static-files.yaml + proxy-http.yaml (if reverse proxy needed)

Critical Rules (Memorize These)

These rules prevent the most common failures:

  1. NEVER use users: directive in cloud-init — Deletes default SSH user, breaks access
  2. Systemd: NO inline comments — After=network.target # comment fails
  3. Permissions as quoted strings — Use '0640' not 0640 in cloud-init
  4. Wait for cloud-init — Takes 2-3 minutes; don't deploy until done
  5. Absolute paths in systemd — Use /opt/app/venv/bin/python not python
  6. Fix permissions after SCP — Files copied retain local permissions

Default Choices for Vague Requests

When the request is ambiguous, use these defaults:

Decision Default Choice Rationale
Application framework Flask/Python Course standard, most examples
Reverse proxy HTTP (not HTTPS) Simpler, use proxy-http.yaml
Application port 5001 Avoids conflict with common ports
Proxy port 80 (HTTP) or 443 (HTTPS) Standard web ports
App directory /opt/<app-name>/ Standard for third-party apps
Config directory /etc/<app-name>/ Standard for system config
Service user <app-name> Same as app, no login shell
Ownership pattern deployuser:servicegroup Deploy user writes, service reads
Directory permissions 775 Group can write (venv installs)
Config file permissions 640 Owner writes, group reads
WSGI server Gunicorn Production-ready, simple config

Example Defaults

"Set up a web application server" → Use:

  • examples/flask.yaml for application VM
  • examples/proxy-http.yaml for proxy VM
  • Port 5001 for Flask, port 80 for nginx

"Configure nginx" → Use:

  • examples/proxy-http.yaml (reverse proxy, not static files)
  • Unless HTTPS explicitly requested, then proxy-https.yaml

"Set up a secure bastion" → Use:

  • examples/bastion.yaml (includes UFW + fail2ban)

Environment Variables Pattern

This is the standard way to handle environment variables (database credentials, API keys, connection strings) on the server.

Directory Structure

/etc/<app-name>/
└── environment      # All environment variables for the application

Setup in Cloud-init

runcmd:
  # Create config directory owned by root, readable by app group
  - mkdir -p /etc/myapp
  - chown root:myapp /etc/myapp
  - chmod 750 /etc/myapp

  # Create environment file with restricted permissions
  - touch /etc/myapp/environment
  - chown root:myapp /etc/myapp/environment
  - chmod 640 /etc/myapp/environment

Reference from systemd

[Service]
EnvironmentFile=/etc/myapp/environment

Environment File Format

# /etc/myapp/environment
DATABASE_URL=postgresql://user:password@host:5432/dbname
SECRET_KEY=your-secret-key-here
API_KEY=external-service-api-key
DEBUG=false

Why This Pattern?

Concern Solution
Security File owned by root, only readable by app group (mode 640)
Separation Config in /etc/, code in /opt/ — different concerns, different locations
Deployment Environment file can be updated without redeploying code
systemd integration EnvironmentFile= loads variables automatically

Quick Reference Tables

Default SSH Users by Cloud Provider

Provider Default User
AWS (Amazon Linux) ec2-user
AWS (Ubuntu) ubuntu
Azure azureuser
GCP Your Google account username
DigitalOcean root
Linode root

File Permission Patterns

Purpose Owner:Group Mode
Application code deployuser:appgroup 640
Application directory deployuser:appgroup 775
Config with secrets root:appgroup 640
Config directory root:appgroup 750
systemd service files root:root 644

Common systemctl Commands

sudo systemctl daemon-reload    # After editing service files
sudo systemctl enable myapp     # Start on boot
sudo systemctl start myapp      # Start now
sudo systemctl status myapp     # Check status
sudo journalctl -u myapp -f     # Follow logs

Cloud-init Verification

cloud-init status               # Check status
cloud-init status --wait        # Block until complete
sudo cat /var/log/cloud-init-output.log  # View logs

Reference Summaries

examples/ directory

Ready-to-use cloud-init YAML files for common server types. Copy and customize for your use case.

cloud-init-patterns.md

Reference documentation for cloud-init syntax:

  • Module execution order
  • Package management (packages, package_update)
  • Writing configuration files (write_files)
  • Running commands (runcmd)
  • Debugging and lifecycle

systemd-patterns.md

Reference documentation for systemd services:

  • Service unit file structure ([Unit], [Service], [Install])
  • Service types (simple, forking, oneshot)
  • Environment configuration
  • Restart policies and resource limits
  • Systemd timers (scheduled tasks, replacement for cron)
  • Managing and debugging services

common-pitfalls.md

Prevention checklist and solutions for:

  • Cloud-init issues (user deletion, timing)
  • systemd issues (inline comments, permissions)
  • File permission problems
  • SSH and networking issues