🌐 English · Português (Brasil)
TWS Panel
Turn an Ubuntu VPS into your own hosting platform.
Harden the server, publish projects with HTTPS and run your own email, all from one open-source panel that you control.
Documentation ·
Installation ·
Help ·
Roadmap ·
Changelog ·
Contributing
Where to start
| Your situation | Go to |
|---|
| 🚀 First installation. You have never installed it, or want every step explained, from the rented VPS to a configured panel and a tested restore. | Step-by-step guidePart 1 installs the panel; Part 2 configures it. |
| 🔁 I reinstalled the VPS, or I am moving to another server. You want the panel, the projects and the email back from the external backups. | Restore on a new VPS |
⚡ I know what I am doing. You have a clean Ubuntu VPS and a user with sudo. | Quick install, one command |
SSH problems when connecting? "REMOTE HOST IDENTIFICATION HAS CHANGED!" is expected after you
reinstall the VPS. See what to do.
[!NOTE]
TWS Panel is in beta. The interface, the commands and the data formats may still change
between versions. The CHANGELOG (in Portuguese) lists what changed in each one.
The panel interface is available in English and Portuguese (Brazil). It picks the language from
your browser and has a selector in the header. Some messages written by the server are still in
Portuguese. The documentation is also in both languages. This README quotes screen names as they
appear in the English interface; the Portuguese README uses the Portuguese ones.
Why it exists
TWS used to rely on a hosting service to publish its clients' websites. One day, a simple change
to a site sat blocked for days with no answer from support. The server was not the problem; depending
on another company to configure everything was. TWS Panel is not a hosting company. It
is the panel that sets up the VPS that you rent, from the provider you choose, and it moves
with you if you switch providers.
Principles:
- Non-invasive: it reuses the Docker already on the machine and leaves what works alone.
- Security first: nothing goes live before the hardening.
- Minimalist: Fastify and JSON files, with no external database.
- Open source: MIT license.
What it does
A short overview. The features guide covers each
item in detail.
Deploy
- Deploy from a git repository (public or private), from your GitHub account or from a folder on the server.
- Detects static HTML, projects with a build step, a
Dockerfile or a docker-compose file (an existing compose file is adopted, not rewritten).
- Multiple domains per project, with an automatic
*.sslip.io address until you have your own.
- Multiple environments from the same repository, such as production and sandbox side by side.
- Encrypted environment variables,
.env import, and deploys that stop when a required variable is missing.
- Port management per container: change, publish, remove or bulk-edit ports, with conflicts shown up front.
- Live deploy logs, with a "Por que falhou" section (written by the server, still in Portuguese; it means "Why it failed") that shows the log of the service that became unhealthy.
HTTPS and the panel domain
- Automatic certificates (Let's Encrypt) for the panel, the projects and email.
- A Certificates page with the status of each certificate, the likely cause when issuing fails, and a "Try issuing now" button.
- Bring your own certificate, with a check that the key and certificate match.
- A custom domain for the panel and, optionally, the ability to turn off access by IP.
Email
- Your own mail server (Stalwart), with DKIM signing (RSA 2048).
- A DNS checklist that the panel verifies (A, MX, SPF, DKIM, DMARC and PTR), with PTR instructions per provider.
- Mailboxes with ready-to-use credentials for Outlook, Gmail or a phone, and a test email.
- Project email: a dedicated mailbox, with
SMTP_* variables injected at deploy.
- Webmail (Roundcube) at
https://mail.<domain>/.
- A Sending page for outgoing mail: queue, history, volume, blocklists and a deliverability score.
Notifications
- Alerts by Telegram, email or both, covering security, deploys, certificates, blocklists, disk and backups.
- Messages leave out the VPS IP, repeated alerts are grouped, and an hourly limit applies.
Backups
- Detects the databases (PostgreSQL, MySQL, MariaDB, MongoDB, Redis), volumes and folders in each project.
- Backups of the panel, the mail server and the projects as
.7z files, with a schedule and retention.
- A copy on the VPS and another on Cloudflare R2 (or other S3-compatible storage), verified after upload.
- Optional encryption of the off-site copy, with a recovery kit.
- Restore item by item, or use "Restore from another server" to rebuild everything on a new VPS.
Security
- A hardening wizard based on Lynis: 8 phases with a dry run, and automatic rollback on the phases that touch access.
- Deploy guardrails that block dangerous configurations (such as an exposed database port or a privileged container). Most blocking rules can be bypassed with an explicit, audited override; the ones that protect the panel's own isolation cannot.
- Continuous monitoring against a baseline, an alert center and an audit log.
- Resource monitoring with no extra agent: processor, memory, disk and network of the VPS and of every project, measured every minute, with traffic lights and 24-hour charts on the Dashboard, a Resources tab per project and alerts for tight memory, a crowded host, slow disk or a container that keeps restarting. It reads the host's
/proc and /sys/fs/cgroup through two read-only mounts; the history retention is configurable.
- Checks of the mail server IP against email blocklists.
- Login with two-step verification (TOTP) and recovery codes.
Web terminal and setup checklist
- A real shell on the server inside the panel, running as the user you choose at install time.
- A Get the panel ready checklist on the Dashboard that shows what is still left to configure.
Installation
This is the short version for people who already know their way around a server. If you prefer
every step explained, follow the step-by-step guide
(see Where to start).
Requirements
- A clean VPS running Ubuntu 22.04 or 24.04 LTS. Recommended minimum: 1 vCPU, 2 GB of RAM and 25 GB of disk.
- Ports 80 and 443 open to the internet (the HTTPS certificate depends on them).
- For email: port 25 unblocked by your provider (many block it on new accounts).
- Docker and everything else the panel needs are installed by the installer.
One command, run as a regular user with sudo (it installs git first if you do not have it):
sudo apt update && sudo apt install -y git \
&& sudo git clone --branch main https://github.com/kelvindk9w/tws-panel.git /opt/tws-panel \
&& sudo chown -R $USER:$USER /opt/tws-panel \
&& cd /opt/tws-panel && ./scripts/install.sh
The installer first checks the machine without changing anything. It then asks which user the
panel terminal should run as, installs Docker, starts the panel and prints the HTTPS address
with the setup token, for example https://203-0-113-10.sslip.io/?token=... (with your own IP).
Open it in your browser and follow the wizard: welcome, machine health, security (hardening) and
the administrator account.
[!WARNING]
First time on a fresh VPS? Create a regular user and install your SSH key before running
the installer: the hardening phase turns off password login over SSH. The
step-by-step guide walks through it, and the security wizard guide
explains how to confirm access without locking yourself out.
[!WARNING]
Reinstalled the VPS and SSH complained "REMOTE HOST IDENTIFICATION HAS CHANGED!"? That is
expected: the VPS has a new identity. Run ssh-keygen -R YOUR_IP on your computer (with the VPS
IP), connect again and answer yes. If you did not reinstall anything, do not continue and do
not run ssh-keygen -R: check the IP and the provider's dashboard first. Details.
After installing
On your first visit, the Dashboard shows the Get the panel ready checklist. The panel checks
the status of each step by itself, and each step has a "How to" section with a
button that opens the right screen.
| # | Step | What it is |
|---|
| 1 | VPS hardening | The hardening phases: updates, SSH with keys only, firewall, blocking of repeated login attempts and auditing. |
| 2 | Two-factor authentication | A 6-digit code from your phone, in addition to your password, to sign in to the panel. |
| 3 | Panel domain | An address of your own (panel.example.com) instead of the one that contains the IP. |
| 4 | Server email (optional) | A mail server on the VPS so your projects can send email. |
| 5 | Notifications (optional) | Telegram or email alerts when something needs your attention. |
| 6 | Off-VPS backups (optional) | An encrypted copy on Cloudflare R2 (or other S3-compatible storage), so you can recover everything on a new VPS. |
Optional steps can be dismissed with "I won't use this". The whole checklist is
also available under Settings → Getting started.
Prefer one ordered walkthrough, from the rented VPS to a first project online and a tested restore?
Follow the step-by-step guide (Part 2 covers this checklist and more).
Scope and trade-offs
- One panel, one VPS. Managing several servers from one panel is not supported (see the roadmap).
- It needs privileged access to the server. The web terminal is a real shell on the VPS, and
the Docker socket mounted into the panel is equivalent to root. This is by design. The
security model explains it, along with what the
project does not protect.
- Built for a clean Ubuntu LTS VPS. The installer checks the machine first and asks for
confirmation if it finds other services in the way.
Documentation
The documentation website is at https://kelvindk9w.github.io/tws-panel/ (English and Portuguese).
The same pages can also be read in this repository, under site/src/content/docs/.
| Guide | Content |
|---|
| Step-by-step guide | Start here for a first installation. Part 1 installs the panel on a clean VPS, with every command explained; Part 2 configures it, up to a tested restore |
| Restore on a new VPS | For when you reinstalled the VPS or are moving to another server: the panel, projects and email back from the external backups |
| Security wizard | The 8 hardening phases, and how to confirm access without locking yourself out |
| Features | What each module does, in detail |
| Prepare your project | What your repository needs to be published: how the panel decides, ready-made recipes, variables, blocking rules and a checklist |
| Operations | Updating, useful commands, emergency scripts, the projects folder, and the terminal user and port |
| Lost access | Lost password, phone, SSH key or panel domain, and how to get back in |
| AI access | API tokens with scope for scripts and AI assistants: create, use, revoke, and what no token can ever do |
| Security model | What the panel protects and what it requires |
| and |
Help and feedback
In a bug report, include the panel version, the operating system of the VPS, the interface language
and the steps to reproduce it. Do not paste logs without reviewing them first: they can contain
domains, IP addresses and tokens. Replace domains with example.com and IP addresses with
203.0.113.10. The page Help and feedback explains how.
Security
Found a vulnerability? Do not open a public issue. SECURITY.md explains how to
report it privately.
Roadmap
ROADMAP.md lists what exists today and what is planned, without dates.
Contributing
Contributions are welcome. CONTRIBUTING.md covers the local setup, the tests, the
project standards and the pull request flow. To run the panel on your own computer, see the
local development guide.
Everyone taking part is expected to follow the Code of Conduct.
About TWS
TWS Panel is maintained by TWS, a software company founded and run by Kelvin Medeiros (CEO).
TWS builds custom web solutions, systems and automations for clients. The project grew out of a
problem the company had itself, and was then opened to the community under the MIT license.
License
MIT © 2026 TWS - Kelvin Medeiros
