{"id":48891528,"url":"https://github.com/penguinztech/penguin-rust-base","last_synced_at":"2026-04-16T08:05:42.941Z","repository":{"id":351117522,"uuid":"1209558717","full_name":"PenguinzTech/penguin-rust-base","owner":"PenguinzTech","description":"Rust dedicated server with Oxide + umod plugins — community base image","archived":false,"fork":false,"pushed_at":"2026-04-13T16:57:59.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T18:25:47.130Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PenguinzTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T14:48:23.000Z","updated_at":"2026-04-13T16:58:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/PenguinzTech/penguin-rust-base","commit_stats":null,"previous_names":["penguinztech/penguin-rust-base"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/PenguinzTech/penguin-rust-base","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PenguinzTech%2Fpenguin-rust-base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PenguinzTech%2Fpenguin-rust-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PenguinzTech%2Fpenguin-rust-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PenguinzTech%2Fpenguin-rust-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PenguinzTech","download_url":"https://codeload.github.com/PenguinzTech/penguin-rust-base/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PenguinzTech%2Fpenguin-rust-base/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31876860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T07:36:03.521Z","status":"ssl_error","status_checked_at":"2026-04-16T07:35:53.576Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-16T08:04:54.004Z","updated_at":"2026-04-16T08:05:42.924Z","avatar_url":"https://github.com/PenguinzTech.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# penguin-rust-base\n\n[![GHCR](https://img.shields.io/badge/ghcr.io-penguin--rust--base-blue)](https://github.com/PenguinzTech/penguin-rust-base/pkgs/container/penguin-rust-base)\n[![Tests](https://github.com/PenguinzTech/penguin-rust-base/actions/workflows/test.yml/badge.svg)](https://github.com/PenguinzTech/penguin-rust-base/actions/workflows/test.yml)\n[![Security](https://github.com/PenguinzTech/penguin-rust-base/actions/workflows/security.yml/badge.svg)](https://github.com/PenguinzTech/penguin-rust-base/actions/workflows/security.yml)\n[![Build](https://github.com/PenguinzTech/penguin-rust-base/actions/workflows/build-image.yml/badge.svg)](https://github.com/PenguinzTech/penguin-rust-base/actions/workflows/build-image.yml)\n\nA production-ready Docker image for Rust dedicated game servers with Oxide mod framework and plugins baked in. Game files (~6GB) are baked at build time to eliminate first-boot download waits. Automatically rebuilds every 4 hours when Oxide or Steam updates, with startup-time checks for plugin updates.\n\nPerfect for operators, communities, and teams extending with proprietary plugins via `FROM`.\n\n📖 **Full configuration reference:** [docs/CONFIGURATION.md](docs/CONFIGURATION.md)\n\n---\n\n## What's Included\n\n- **Rust Dedicated Server** — Steam app 258550, latest version\n- **Oxide Mod Framework** — Auto-updated every 4 hours\n- **Pre-Installed Plugins** — all plugins published to [penguin-rust-plugins](https://github.com/PenguinzTech/penguin-rust-plugins) are automatically baked in on every image build (no static list to maintain):\n  - **AdminUtilities** — Admin commands (noclip, god mode, kick, ban, give, spawn)\n  - **BGrade** — Automatically upgrade building grades\n  - **CopyPaste** — Copy and paste buildings\n  - **Vanish** — Admin invisibility toggle\n  - **RemoverTool** — Remove placed objects\n  - **UnburnableMeat** — Prevents cooked meat from burning\n  - **VehicleDecayProtection** — Per-vehicle decay protection permissions\n  - **NightLantern** — Auto-lights fires/lanterns at night\n  - **TruePVE** — PvE protection rules\n  - **StackSizeController** — Customize item stack sizes\n  - **Whitelist** — Restrict server access to whitelisted players\n- **AutoAdmin Plugin** — Custom PenguinzTech plugin that auto-grants all baked and patched plugin permissions to admins on every boot via `RUST_ADMIN_STEAMIDS`; also fires on plugin hot-reload so no manual `oxide.grant` calls are needed\n- **PluginManager Plugin** — Runtime `/plugin add|remove|update|list` commands; manage plugins live without a restart (see [docs/plugin-manager.md](docs/plugin-manager.md))\n- **Patched Community Plugins** — 10 popular community plugins pre-patched for Oxide API compatibility (removed APIs replaced so they work on current Rust builds): AntiOfflineRaid, BetterChat, BetterChatMute, DynamicPVP, NTeleportation, PlayerAdministration, Quests, TreePlanter, VehicleLicence, ZoneManager — see [docs/ACKNOWLEDGEMENTS.md](docs/ACKNOWLEDGEMENTS.md)\n- **WAF Sidecar** — Go-based network-layer firewall that protects the game server from DDoS floods, cheater reconnect storms, RCON brute-force, and packet anomalies — **works in pure vanilla mode** with no Oxide required (see [docs/waf.md](docs/waf.md))\n- **Auto-Configuration** — First-boot tuning of `worldSize`/`maxPlayers` based on available CPU/RAM\n- **Wipe Scheduler** — Configurable map wipes with in-game RCON warnings (60-minute lead time)\n- **DDoS Protection** — Per-source-IP rate limiting via iptables (opt-in, requires `NET_ADMIN`)\n- **Debian 12 Bookworm Runtime** — Lightweight, secure, production-hardened container\n\n---\n\n## Quick Start\n\n### Basic Server (auto-tuned world size and player limit)\n\n```bash\ndocker run -d \\\n  --name rust-server \\\n  -p 28015:28015/udp \\\n  -p 28015:28015/tcp \\\n  -p 28016:28016/tcp \\\n  -e RUST_SERVER_NAME=\"My Rust Server\" \\\n  ghcr.io/penguinztech/penguin-rust-base:latest\n```\n\n### With Admin Access + Persistent Volume\n\n```bash\ndocker run -d \\\n  --name rust-server \\\n  -p 28015:28015/udp \\\n  -p 28015:28015/tcp \\\n  -p 28016:28016/tcp \\\n  -v rust-data:/steamcmd/rust/server \\\n  -e RUST_SERVER_NAME=\"My Rust Server\" \\\n  -e RUST_ADMIN_STEAMIDS=\"76561198000000000,76561198000000001\" \\\n  ghcr.io/penguinztech/penguin-rust-base:latest\n```\n\n### Docker Compose\n\n```yaml\nservices:\n  rust:\n    image: ghcr.io/penguinztech/penguin-rust-base:latest\n    container_name: rust-server\n    ports:\n      - \"28015:28015/udp\"\n      - \"28015:28015/tcp\"\n      - \"28016:28016/tcp\"\n    volumes:\n      - rust-data:/steamcmd/rust/server\n    environment:\n      RUST_SERVER_NAME: \"My Community Server\"\n      RUST_SERVER_DESCRIPTION: \"Weekly wipes, friendly community\"\n      RUST_SERVER_TAGS: \"weekly,vanilla,pvp\"\n      WIPE_SCHED: \"1w\"\n      WIPE_DAY: \"Th\"\n      RUST_ADMIN_STEAMIDS: \"76561198000000000\"\n    restart: unless-stopped\n\nvolumes:\n  rust-data:\n```\n\n---\n\n## Configuration\n\nAll settings are controlled via environment variables. The most commonly set ones:\n\n| Variable | Default | Description |\n|---|---|---|\n| `RUST_SERVER_NAME` | `Rust Server` | Server name in browser |\n| `RUST_SERVER_MAXPLAYERS` | *(auto-detected)* | Max concurrent players |\n| `RUST_SERVER_WORLDSIZE` | *(auto-detected)* | Map size in meters |\n| `RUST_SERVER_SEED` | `12345` | World seed |\n| `RUST_RCON_PASSWORD` | *(auto-generated)* | RCON password; generated and persisted to PVC if unset |\n| `RUST_ADMIN_STEAMIDS` | *(none)* | Comma-separated admin Steam IDs |\n| `WIPE_SCHED` | *(first Thu of month)* | `1w`, `2w`, `3w`, or `off` |\n| `PLUGIN_SOURCE` | `github` | `github` (baked→GitHub→umod chain), `baked` (no network), or `umod` (always umod.org) |\n| `PLUGIN_UMOD_FALLBACK` | `1` | In `github` mode, fall back to umod.org for slugs not in penguin-rust-plugins (`0` to disable) |\n\n📖 **Everything else** — browser listing (description, tags, URL, logo), server behaviour (PvE, radiation, tickrate), wipe schedule details, DDoS protection, admin provisioning, plugin toggles, auto-config tiers, performance tuning — is documented in **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**.\n\nSpecialist guides:\n- **[docs/auto-config.md](docs/auto-config.md)** — first-boot resource detection, lock file behaviour\n- **[docs/wipe-schedule.md](docs/wipe-schedule.md)** — wipe cadence, blueprint wipes, warning schedule\n- **[docs/ddos-protection.md](docs/ddos-protection.md)** — iptables rate limiting and auto-ban\n- **[docs/waf.md](docs/waf.md)** — Go WAF sidecar: vanilla-compatible DDoS/flood/cheat protection, Oxide integration, Prometheus metrics\n\n---\n\n## Image Tags \u0026 Versioning\n\nEvery build produces two tags:\n\n| Tag | Mutability | Use Case |\n|-----|-----------|----------|\n| `latest` | Mutable | Development, testing — always get the newest Oxide/Steam updates |\n| `\u003cunix-epoch\u003e` | Immutable | Production, pinning — freeze a known-good build |\n\n```bash\n# Pin to a specific build in production\nFROM ghcr.io/penguinztech/penguin-rust-base:1747123456\n```\n\nList available tags:\n```bash\ncurl -s https://ghcr.io/v2/penguinztech/penguin-rust-base/tags/list | jq '.tags'\n```\n\n---\n\n## Extending This Image\n\n```dockerfile\nFROM ghcr.io/penguinztech/penguin-rust-base:1747123456\n\n# Custom/proprietary plugins\nCOPY --chown=rustserver:rustserver my-plugins/ /steamcmd/rust/oxide/plugins/\n\n# Pre-seeded plugin data\nCOPY --chown=rustserver:rustserver my-data/ /steamcmd/rust/oxide/data/\n\n# Default overrides\nENV RUST_SERVER_NAME=\"My Custom Server\"\n```\n\n---\n\n## Plugin Caching\n\nPlugins are baked into the image as gzip-compressed `.cs.gz` files alongside a `.hash` sidecar. This serves two purposes:\n\n**Startup speed** — On every boot, `start.sh` compares the baked hash against the latest release in `penguin-rust-plugins`. If they match, the plugin is decompressed and activated in milliseconds from the local layer — no network round-trip. Only plugins that have been updated since the image was built are downloaded at startup.\n\n**Efficient layer sharing for multi-server providers** — All plugin `.cs.gz` files live in a single immutable Docker layer. Hosts running many Rust server containers (or different server images built `FROM` this base) share that layer on disk and in the registry pull cache. Plugins are only decompressed into the container's writable layer when activated, so the compressed originals remain shared.\n\n```\noxide/plugins/disabled/     ← shared, compressed, in image layer\n    truepve.cs.gz\n    truepve.hash\n    whitelist.cs.gz\n    whitelist.hash\n    ...\n\noxide/plugins/              ← per-container writable layer, uncompressed\n    TruePVE.cs              ← only after RUST_PLUGINS=truepve\n    Whitelist.cs\n```\n\nPlugins are disabled by default. Set `RUST_PLUGINS` to activate specific ones:\n\n```bash\n-e RUST_PLUGINS=\"truepve,whitelist,vanish\"\n```\n\n---\n\n## Automatic Updates\n\n- **Every 4 hours** — check Oxide and Steam for updates, rebuild if changed\n- **On dispatch** — manual `gh workflow run build.yml`\n- **On startup** — compare baked plugin hashes against latest `penguin-rust-plugins` releases; download updates only when needed\n\n---\n\n## WAF Sidecar (Network-Layer Protection)\n\nThe image ships a **Go WAF sidecar** that operates at the network layer — below the Rust game engine. It intercepts all traffic before it reaches the single-threaded C#/Mono game loop and drops malicious packets in Go's concurrent runtime where they are cheap.\n\n**Crucially, this works on pure vanilla servers.** No Oxide, no plugins, no mods required. Every protection below runs at the packet level regardless of server configuration:\n\n| Protection | How it works |\n|---|---|\n| **DDoS / flood** | Per-IP packet-rate limiter; sustained floods auto-blocked |\n| **RCON brute-force** | Failed auth counter; offending IP throttled after N attempts |\n| **Ban evasion** | Steam64 ID extracted from handshake; banned player blocked across IP changes |\n| **Packet anomalies** | Malformed/oversized packets dropped before game sees them |\n| **Aimbot heuristics** | Inter-packet timing CV analysis; bot-like consistency flagged |\n\nWhen Oxide *is* running, plugins can push runtime rules to the WAF via a loopback REST API — reporting detected cheaters for immediate network-layer enforcement without a game restart.\n\nEnable in Kubernetes (Helm):\n\n```bash\nhelm install rust-server ./k8s/helm/rust-server --set waf.enabled=true\n```\n\n📖 **Full WAF reference:** [docs/waf.md](docs/waf.md)\n\n---\n\n## Networking\n\n| Port | Protocol | Purpose |\n|------|----------|---------|\n| `28015` | UDP + TCP | Game server port (connections + queries) |\n| `28016` | TCP | RCON / WebRCON |\n| `28017` | UDP | Server browser query |\n\nForward **both UDP and TCP** on port 28015. RCON and query ports are optional.\n\n\u003e **WAF port note:** When the WAF sidecar is enabled, it occupies the public-facing ports (`28015/28016/28017`) and shifts the game server to loopback offsets (`28115/28116/28117`). No change to external port mappings required.\n\n---\n\n## Security\n\nRuns as non-root (`rustserver:rustserver`, UID 1000); no capabilities required unless DDoS protection is enabled. RCON password auto-generated on first boot and persisted to the PVC — never embedded. The WAF sidecar also runs as a dedicated non-root user (`waf:waf`) and adds zero inbound attack surface — its management API listens on loopback only.\n\nFull details — CI scanners, what's not scanned, reporting vulnerabilities: **[docs/SECURITY.md](docs/SECURITY.md)**.  \nDDoS protection setup: **[docs/ddos-protection.md](docs/ddos-protection.md)**.  \nWAF sidecar: **[docs/waf.md](docs/waf.md)**.\n\n---\n\n## Troubleshooting\n\n```bash\n# Check logs\ndocker logs rust-server | tail -50\n\n# Server won't start — typical causes:\n# - Port conflict on 28015/28016\n# - Memory limit below MONO_MAX_HEAP\n# - Volume permissions (must be writable by UID 1000)\n\n# Retrieve auto-generated RCON password\ndocker exec rust-server cat /steamcmd/rust/server/rust_server/.rcon.pw\n\n# Plugin status\ndocker exec rust-server ls /steamcmd/rust/oxide/plugins/\ndocker exec rust-server tail -50 /steamcmd/rust/server/oxide/logs/log.txt\n```\n\nFull troubleshooting: [docs/CONFIGURATION.md](docs/CONFIGURATION.md)\n\n---\n\n## Contributing\n\nIssues, feature requests, and pull requests welcome on [GitHub](https://github.com/PenguinzTech/penguin-rust-base).\n\n---\n\n## License\n\n- **Container image:** MIT License\n- **Bundled plugins:** Their respective authors' licenses (see [umod.org](https://umod.org))\n- **Rust / Steam:** Licensed by Facepunch Studios — by using this image you agree to the [Rust Server License](https://www.rust.facepunch.com/)\n\n---\n\n## Support\n\n- [GitHub Issues](https://github.com/PenguinzTech/penguin-rust-base/issues) — image-specific issues\n- [Rust Support](https://support.facepunch.com/) — game server issues\n- [Oxide Docs](https://umod.org/documentation) — mod framework\n- [umod Community](https://umod.org/community) — plugin help\n\n---\n\n**Built by PenguinzTech** — Reliable, production-ready Rust infrastructure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenguinztech%2Fpenguin-rust-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpenguinztech%2Fpenguin-rust-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenguinztech%2Fpenguin-rust-base/lists"}