Set Up Doudizhu and Add Remote Access with Localtonet

Identify the repository and pin an immutable revision

This article concerns svzdev/doudizhu. Its README describes a Python and Tornado backend, MySQL persistence, and a Phaser frontend. It documents Python 3.8 or newer, MySQL 5.7 or newer, the DATABASE_URI environment variable, startup with python3 app.py, and the address http://127.0.0.1:8080. These are repository documentation claims, not a compatibility certification for every newer software version.

The README still instructs readers to clone mailgyc/doudizhu. We use the explicitly identified svzdev/doudizhu repository instead. Instructions for other Dou Dizhu projects, including opening a single HTML file or starting an unrelated Node application, do not apply here.

The supplied commit history identifies 7092ea77cb1273c3726ecd8b9be03d9f489eb8ed as the observed master revision. Unlike a branch name, this full commit identifier is an immutable source reference. It does not establish successful installation, security review, or remote gameplay.

For a fresh review checkout, use the actual observed SHA rather than a placeholder or a movable branch:

git clone https://github.com/svzdev/doudizhu.git
cd doudizhu
git checkout --detach 7092ea77cb1273c3726ecd8b9be03d9f489eb8ed
git rev-parse HEAD
git status --short

The reported SHA should match exactly. A detached checkout is appropriate for inspecting a fixed revision; it is not an error. Record any local changes separately so later troubleshooting does not silently mix original source with deployment patches.

Review the same revision's README, schema.sql, requirements.txt, and server directory. If testing selects a different revision, update every setup-critical reference and rerun the checks. Pinning source alone does not necessarily pin transitive dependencies or the host environment.

Understand the local and remote request paths

This is not a standalone HTML page. The browser-facing resources belong to a running application, and persistence depends on MySQL. The reviewed template directory includes index.html and poker.html, but their presence does not prove that every frontend asset required by the current client is ready to serve.

In the remote path, a browser reaches the Localtonet public endpoint, which forwards traffic to Tornado. Tornado accesses MySQL as needed. Players do not need a database connection, and a tunnel does not replace the backend, compile the client, initialize tables, or grant application permissions.

Standard HTTP tunneling is not a VPN. It publishes the selected service, not a private network membership. It also does not establish who is authorized to use the game. Authentication, room restrictions, and any multiplayer connection mechanism must be inspected and tested in the pinned application.

Prepare the host and resolve client requirements

Use a host where you can install Python dependencies, run the backend, and administer or reach a MySQL server. The repository evidence does not prescribe an operating-system package manager, service supervisor, or production deployment platform. Use supported installation methods for your operating system rather than assuming a particular Linux distribution.

These POSIX-shell commands inspect tools and tracked source without installing packages:

python3 --version
python3 -m pip --version
mysql --version
git rev-parse HEAD
git ls-tree -r --name-only HEAD client
git show HEAD:requirements.txt
git show HEAD:schema.sql

mysql --version reports the client version, not necessarily the connected server version. Query SELECT VERSION(); after connecting to record the server actually used.

An isolated Python environment reduces conflicts with system packages. Where the standard venv module is available, a general POSIX setup is:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip --version

This is general Python environment preparation, not a repository-prescribed tool choice. Availability and activation differ by operating system. Use the same environment for dependency installation and application startup.

Do not skip the TypeScript client inspection

History records a Phaser 3 client migration from JavaScript to TypeScript on July 22, 2026. The root README still presents only the older Python quick start. Neither fact alone tells us whether generated browser assets are committed, whether a frontend build is mandatory, or how build output reaches Tornado.

Inspect the pinned client directory before treating backend startup as complete. Identify any package manifest, lockfile, tool-version declarations, TypeScript configuration, build configuration, and client-specific instructions. Read the scripts actually declared there rather than assuming a conventional build command.

• Determine whether browser-ready JavaScript is already present in a clean checkout.
• If compilation is required, establish the supported runtime, package manager, dependency-install command, and build command from that revision.
• Identify the output directory and how Tornado templates or static-file handlers reference it.
• Check whether development and deployed client modes expect different origins or ports.
• Record every preparation step, then repeat it in a fresh checkout without leftover generated files.

Create and verify the ddz database

The available schema.sql is explicit: it creates ddz with character set utf8mb4 and collation utf8mb4_general_ci, then creates ddz.user and ddz.record. All three creation statements use IF NOT EXISTS. The file does not provision a dedicated application account or define its grants.

These definitions establish storage structure, not game semantics or authentication guarantees. For example, a unique openid column does not by itself establish that incoming identities are securely authenticated. The schema also contains no seed inserts, so there is no documented seed-row count to require.

From the project root, the README's initialization command is:

mysql --user=root -p < schema.sql

The password prompt avoids putting an administrative password in the command. Use a reviewed administrative account appropriate to your environment if root access is managed differently. Import into a disposable test database environment first, not an existing installation containing valuable game data.

Verify objects and column definitions

Read all import errors and check the command's exit status immediately. Then run the following read-only queries through an administrative inspection session:

SELECT VERSION();
SHOW DATABASES LIKE 'ddz';
SHOW TABLES FROM ddz;
SHOW COLUMNS FROM ddz.`user`;
SHOW COLUMNS FROM ddz.`record`;
SHOW CREATE TABLE ddz.`user`;
SHOW CREATE TABLE ddz.`record`;

For a clean import, expect the two documented tables and the definitions summarized above. IF NOT EXISTS does not upgrade an existing table with missing or outdated columns. A successful repeated import is therefore not sufficient evidence that an older database matches the pinned source.

Provision and test a dedicated account

Administrative schema creation and routine application access are different responsibilities. Have a MySQL administrator inspect the pinned application queries and provision a dedicated account restricted to the necessary operations on ddz. The evidence does not establish an exact least-privilege grant set or account-host pattern, so a universal CREATE USER/GRANT script would be speculative.

After provisioning, replace APP_DB_USER with that actual username and test the same network path the backend will use:

mysql --user=APP_DB_USER -p --host=127.0.0.1 --port=3306 ddz

SELECT CURRENT_USER(), DATABASE();
SHOW TABLES;
SELECT COUNT(*) FROM `user`;
SELECT COUNT(*) FROM `record`;

These checks establish connection, selected database, and read access. They do not establish permission to perform all application writes. Test representative database-backed game actions and inspect failures before expanding grants. Do not solve a permission problem by switching the application back to root.

Follow the documented backend startup sequence

The sequence below preserves the README's backend order while using the named repository, immutable revision, and a dedicated database account. Resolve frontend preparation separately before declaring the application usable. Review requirements.txt before installation; a pinned source file is not necessarily a fully locked dependency environment.

mysql --user=root -p < schema.sql

python3 -m pip install -r requirements.txt

cd server

export DATABASE_URI='mysql+aiomysql://APP_DB_USER:APP_DB_PASSWORD@127.0.0.1:3306/ddz'

python3 app.py

The export uses POSIX-shell syntax. Encode password characters with special URI meaning according to the driver's connection-URL rules. Do not publish the completed URI, commit it, or include it in screenshots and support logs. Shell history may also retain commands containing secrets; use your environment's approved secret-handling method for ongoing operation.

An environment variable normally passes to processes started from that shell. A new login, service manager, or reboot will not automatically reproduce it. The repository does not prescribe a production secret store or process supervisor, and the foreground command is not a promise of automatic restart.

Verify the entire local browser workflow

Open http://127.0.0.1:8080 on the application host. A page response establishes only that a listener returned content. It does not prove that generated client assets exist, database writes succeed, or participants can exchange game state.

• Confirm that the expected page loads and the Python process remains running.
• Open browser developer tools. Check scripts, styles, images, and other assets for missing files, incorrect content types, or JavaScript errors.
• Confirm that assets originate from the intended pinned build, not a stale browser cache or a previous checkout.
• Follow the interface's actual game flow, including session entry and representative actions.
• Identify requests associated with database activity and verify their effects with appropriate read-only queries. Do not invent expected row counts or assume every action creates a record.
• If multiple participants are supported, use independent browser contexts and observe state changes in each.
• Refresh or reconnect a browser and record actual recovery behavior.

The supplied excerpts do not establish a health-check endpoint, an automated game test, the exact session workflow, or whether browser updates use WebSocket, polling, or another mechanism. Identify the mechanism from the pinned code and browser network panel rather than asserting one.

Test again from the device that will run our client. If it is the application host, loopback is appropriate. If it is another device, 127.0.0.1 refers to that other device, not the game server. Verify an approved private address reachable from the client, including the backend's binding and local network access policy. Running our client on the game host avoids this extra LAN boundary.

Do not proceed when local verification fails. A tunnel cannot repair a missing client build, failed schema import, absent Python module, bad credential, or stopped backend.

Forward the verified HTTP service with Localtonet

Our client establishes an outbound connection to a Localtonet relay. This provides public access without inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes for the tunnel. Use the service only where your network policy permits it; tunneling is not permission to bypass organizational controls.

HTTP tunnels support Random Sub Domain, Custom Sub Domain, or Custom Domain process types, subject to current availability and plan options. Each serves the local content at a public HTTPS address. Select available relays from the current dashboard rather than hardcoding a region or server code. For custom domains, consult the current DNS requirements before configuring records.

The following uses our standard tunnel lifecycle. Keep the HTTP tunnel documentation available for current installation and dashboard details.

Test remote assets, connections, and gameplay

Use a browser on a separate network when practical. Keep backend logs and our client status available, then repeat the workflow that succeeded locally:

1. Load the assigned public HTTPS URL and confirm the expected page.
2. Check that scripts, images, styles, and subsequent page requests succeed.
3. Inspect browser errors for mixed content, origin checks, or hardcoded private addresses.
4. Exercise the actual session and gameplay workflow with independent participants where supported.
5. Verify representative database-backed actions using the dedicated account.
6. Observe any persistent or bidirectional connections throughout the session, not just during connection establishment.
7. Disconnect and reconnect a test browser, then compare recovery with local behavior.
8. Review backend and browser errors before distributing the link more broadly.

A remote browser interprets 127.0.0.1 as itself. If a client script constructs a connection to localhost or a private host, the initial public page can work while gameplay fails. Compare local and public network traces, including request origins, paths, responses, and connection lifetimes.

If client and backend preparation reveals additional service ports, do not assume forwarding 8080 automatically publishes them. Determine the supported deployment arrangement and retest it. This article does not certify remote multiplayer for the observed revision without those results.

Record results, restart, and shut down safely

Availability depends on the Python process, required MySQL access, the connected Localtonet client, and a running tunnel. A configuration visible in the dashboard is not proof that all four conditions hold.

Clean-environment acceptance record

Before publishing this as a completed installation tutorial, the editor must retain a reproducible test record covering:

• The full source SHA, operating system, Python version, and connected MySQL server version.
• Dependency installation from an empty environment, including client tool versions and build commands if required.
• Schema import into a clean database, with both table definitions checked.
• Dedicated account behavior for real reads and writes, not just successful login.
• Backend startup and static assets from a clean checkout.
• Browser connection types and the exact local game flow tested.
• The same flow through Localtonet, with participant count and observed limitations.
• Restart, browser reconnection, tunnel stop, application stop, and public-access shutdown results.

These are acceptance criteria, not reported successes. The final published instructions should incorporate the verified client procedure and resolved compatibility requirements rather than leaving readers to rediscover them.

Restart behavior

Stop public forwarding during maintenance. Restart the backend from the pinned checkout's server directory with the same Python environment and a valid credential source. A new shell may lack DATABASE_URI. Verify locally before restarting public access.

After a host or client reboot, check the Localtonet device connection and tunnel state explicitly. Do not promise automatic startup without a separately configured and tested supervisor. Re-test database-backed behavior and browser reconnection; persistence of stored records does not necessarily imply persistence of an active game session.

Security and shutdown

Review debug settings, administrative handlers, input validation, dependencies, and authentication before exposure to untrusted users. A recent dependency commit is not a security audit. Use least privilege, restrict database access, and retain only redacted logs without tokens, complete connection URIs, session secrets, or personal data.

Stop the tunnel first when the session ends, then verify that the public URL no longer reaches the application. Stop the foreground Python process using your operating system's normal interruption procedure. Stop MySQL only if it is dedicated to this environment and no other service depends on it. Back up valuable data before schema changes; do not use repeated imports as a migration or recovery strategy.

Troubleshoot the failing boundary

Some database failures appear only when an action first accesses persistence. Reproduce the problem locally before changing the tunnel. Likewise, test from the Localtonet client device before blaming public routing: a successful browser on the game host says nothing about a different device's loopback address.

Frequently asked questions