October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix NowOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
VGSources
Blog

How to Deploy CherryPy Web Apps Behind an Nginx Reverse Proxy

Run CherryPy privately behind Nginx, preserve host and client metadata, serve static files efficiently, and choose correctly between CherryPy’s HTTP server and a uWSGI WSGI process.
Length10 min Posted Quest giverVGSources Team
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run CherryPy on a private local port, put Nginx on the public hostname, and have Nginx forward dynamic requests with the original host and client-address headers. CherryPy’s proxy tool then restores the public URL and client context inside the application. You can keep CherryPy’s own production-ready HTTP server or place a WSGI server such as uWSGI between Nginx and the application; the choice changes the endpoint and protocol that proxy_pass must use.

What the deployment looks like

The reliable pattern is to separate the public edge from the Python application. Nginx listens on the public interface for the site’s hostname. CherryPy listens only on a private application endpoint such as 127.0.0.1:8080. Nginx accepts the browser’s request, optionally serves static files itself, and proxies the remaining paths to CherryPy.

As an Amazon Associate I earn from qualifying purchases.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

That arrangement gives you one public entry point while keeping the application listener off the public network. It also leaves room for multiple CherryPy instances behind one Nginx upstream. CherryPy’s deployment documentation describes reverse proxying as a common and easy setup, and documents both its own HTTP server and WSGI-based hosting.

Request path

  1. A browser requests the public hostname, for example www.example.com.
  2. Nginx receives the request on its public listener.
  3. Requests under /static/ can be mapped directly to files by Nginx.
  4. Other paths are sent to the configured upstream, such as 127.0.0.1:8080.
  5. Nginx forwards the host and client-address headers.
  6. CherryPy’s proxy tool uses those headers and the configured public base URL when the application builds URLs or reads request metadata.

Choose the application process model first

Nginx must point to the protocol and endpoint that actually exist behind it. Decide whether CherryPy will accept HTTP directly or whether a WSGI server will expose the application.

#1 Best Overall
Sale
Gaoye Blue Light Blocking Glasses
  • BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
  • EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
  • COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
  • LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
  • WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.

Direct CherryPy HTTP server

CherryPy’s own HTTP server is documented as production-ready. In this model, CherryPy binds to a local HTTP port, and Nginx uses an HTTP proxy_pass target for that listener. This is the simplest deployment path and the baseline shown in the official deployment material.

CherryPy application hosted through uWSGI

For a WSGI process model, the application exposes a WSGI callable, CherryPy’s built-in HTTP server is disabled, the CherryPy engine is started, and uWSGI listens on a local endpoint. The documented example runs:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
uwsgi --socket 127.0.0.1:8080 --protocol=http --wsgi-file mymod.py --callable wsgiapp

Because that command exposes HTTP on the local socket through --protocol=http, Nginx still proxies HTTP to the endpoint. If you choose a different uWSGI protocol or socket arrangement, the Nginx upstream must be changed to match it; do not copy a proxy_pass value from the direct-CherryPy model without checking the listener.

Prepare CherryPy on a private listener

Set listener options in CherryPy’s global server configuration. The following minimal application configuration uses port 8080 and enables proxy awareness for a public site at http://www.example.com:

Rank #2
Windex Gaming Cleaning Wipes, Pre-Moistened Wipes to Instantly Clean all Gaming Gear and Electronics, Resealable Packaging for a Freshness Lock, 25 count (Pack of 1)
  • WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
  • AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
  • PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
  • ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
  • COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
import cherrypy

cherrypy.config.update({
    "server.socket_port": 8080,
    "tools.proxy.on": True,
    "tools.proxy.base": "http://www.example.com",
})

cherrypy.quickstart(Root())

Replace Root() with your application’s root object and replace the hostname with the value used by the Nginx server_name. The port is an example; use the same port in Nginx’s upstream block.

Why the proxy tool matters

Without proxy-aware settings, the application can see Nginx’s address instead of the original client address and can construct links against the internal listener rather than the public site. The official CherryPy guidance uses tools.proxy.on so CherryPy can use the forwarded client information and tools.proxy.base so its public URL context matches the configured hostname.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keep the base URL aligned with the public scheme and host that users actually reach. If TLS is terminated at Nginx, the externally visible scheme is HTTPS; configure the application’s public base accordingly for links and redirects. The baseline configuration in the documentation uses HTTP, so change it when your deployed public URL differs.

Configure Nginx as the reverse proxy

Create an Nginx configuration for the public hostname. The representative CherryPy configuration below defines two possible application listeners, serves static files directly, and proxies every other path:

Rank #3
Sale
LISEN Cell Phone Stand Phone Holder for Desk, Office Decor Gadgets for Men
  • Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
  • Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
  • Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
  • ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
  • Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
upstream apps {
  server 127.0.0.1:8080;
  server 127.0.0.1:8081;
}

server {
  listen 80;
  server_name www.example.com;

  location ^~ /static/ {
    root /app/static/;
  }

  location / {
    proxy_pass http://apps;
    proxy_redirect off;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $server_name;
  }
}

Adapt the hostname, filesystem path, and listener addresses to the host. On Ubuntu, the CherryPy guide instructs operators to save the file under /etc/nginx/conf.d/; follow the layout used by your operating system if it differs.

What each part does

  • upstream apps: Names the group of application endpoints that Nginx can forward to.
  • server 127.0.0.1:8080 and server 127.0.0.1:8081: Identify two local CherryPy instances. If you run only one instance, keep only the listener that exists.
  • listen 80: Accepts public HTTP traffic in this baseline.
  • server_name: Declares the hostname that should select this virtual server. It should match the public name used in CherryPy’s proxy base setting.
  • location ^~ /static/: Sends static URL paths to Nginx’s filesystem handler instead of the application.
  • proxy_pass http://apps: Forwards dynamic requests to the upstream group. Nginx’s reverse-proxy documentation identifies proxy_pass as the basic forwarding mechanism.
  • proxy_redirect off: Prevents Nginx from rewriting redirect headers in this representative setup.
  • Host, X-Real-IP, X-Forwarded-For, and X-Forwarded-Host: Carry the public host and client-address chain to CherryPy.

Understand the forwarded headers

The header settings are not decorative; they preserve information lost when a reverse proxy terminates the client connection.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Header Value in the baseline Purpose
Host $host Passes the requested hostname to the application.
X-Real-IP $remote_addr Passes the address of the client that connected to Nginx.
X-Forwarded-For $proxy_add_x_forwarded_for Preserves the existing forwarding chain while adding the current client address.
X-Forwarded-Host $server_name Passes the public virtual-server hostname.

CherryPy’s proxy tool is the application-side counterpart to these headers. Enable it when routes, redirects, logging, or access decisions need the public host and original client context. Ensure your application treats forwarded headers as trusted only when requests can reach it through the trusted proxy path; exposing the application listener publicly would allow clients to supply misleading values.

Deploy step by step

  1. Choose a private port. Select an unused local endpoint such as 127.0.0.1:8080. If you plan two instances, choose a second port such as 127.0.0.1:8081.
  2. Start CherryPy directly. Launch the application with server.socket_port set to the selected port. For a WSGI deployment, instead expose the callable through the documented uWSGI command and disable CherryPy’s built-in HTTP server.
  3. Test the local listener first. Request the application through its local endpoint before adding Nginx. Confirm that the expected route responds and that startup logs show the intended port. This isolates application failures from proxy errors.
  4. Write the Nginx configuration. Add the upstream and server blocks, adapting paths, hostname, and ports. Keep the upstream protocol consistent with the process model.
  5. Check the Nginx configuration. Run the platform’s Nginx configuration test command (commonly nginx -t) and correct every syntax or path error before reloading.
  6. Reload Nginx. Reload the service using the service manager on the host. A reload applies the validated configuration without requiring you to stop the application process.
  7. Test the public hostname. Request a dynamic route through the hostname in server_name. Inspect the CherryPy log to verify that the forwarded host and client address are the values your application expects.
  8. Test static paths separately. Request a known file below /static/ and confirm that Nginx finds it without invoking a dynamic route. A dynamic success does not prove that the filesystem mapping is correct.
  9. Test each configured instance. When ports 8080 and 8081 are both listed, stop one instance temporarily and make requests through Nginx. Confirm that the remaining instance handles traffic as your availability plan expects, then restore the stopped process.

Serve static assets safely and efficiently

The documented example places /static/ in a direct Nginx location. This keeps routine file delivery out of the CherryPy request path and lets the application concentrate on dynamic work.

Rank #4
Ledagic IC+RGBW USB Powered Led Light Bar with App & Remote Control, 2 Pack
  • Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
  • Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
  • 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
  • Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
  • USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC

The shown root /app/static/; is only an example filesystem location. Verify that the directory exists, that the Nginx worker can read it, and that the URL-to-file mapping is what you intend. A request for /static/css/site.css must resolve beneath the configured root according to your Nginx location layout. Check both a file that should exist and a path that should return a missing-file response.

Do not place a broad static location over dynamic routes accidentally. Keep the ^~ /static/ prefix and the application’s URL conventions aligned, then exercise static and dynamic paths independently after every configuration change.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Scale to more than one CherryPy instance

An Nginx upstream can list multiple CherryPy listeners. The documented pair, ports 8080 and 8081, gives Nginx two destinations and enables its upstream load-balancing behavior. Each process must run the same application version and expose the routes that Nginx may send to it.

Adding a second line does not start a second process. You must launch the additional CherryPy instance yourself, configure it to listen on the second port, and monitor both processes. During a rollout, validate one listener locally before adding it to the upstream. If an instance is stopped while it remains configured, requests assigned to it can fail; use the temporary-stop check to learn how your chosen Nginx behavior appears to clients and logs.

Best Value
Sale
HUANUO FlowLift™ Dual Monitor Stand, Fully Adjustable Gaming Monitor Desk Mount for 13–32″ Computer Screens, Full Motion VESA 75x75/100x100 with C-Clamp & Grommet Base, Each Arm Holds 4.4 to 19.8 lbs
  • Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
  • Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
  • Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
  • Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
  • Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.

Applications that keep user state only in process memory need an explicit session strategy before requests can move between instances. The supplied Nginx and CherryPy baseline does not define session storage or affinity, so make that an application-level decision rather than assuming that two upstream lines provide seamless state sharing.

Direct CherryPy or uWSGI?

Choice Listener model Nginx target What you configure
CherryPy HTTP server CherryPy binds its own local HTTP port, such as 127.0.0.1:8080. An HTTP upstream pointing at that port. Set server.socket_port; enable proxy settings when needed.
uWSGI WSGI process CherryPy’s built-in server is disabled; uWSGI exposes the WSGI callable on a local endpoint. An upstream matching the uWSGI protocol and endpoint; the documented command exposes HTTP on port 8080. Define the callable, start the CherryPy engine, and launch uWSGI with the selected options.

There is no requirement to add uWSGI merely because Nginx is present. CherryPy’s own server is a supported production baseline. Choose uWSGI when its WSGI process model fits your operational design, and then make Nginx’s upstream reflect the exact interface uWSGI provides.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

HTTPS, redirects, timeouts, and buffering are separate decisions

The baseline configuration listens on port 80 and demonstrates HTTP proxying. A production site may terminate TLS at Nginx, redirect HTTP to HTTPS, or require application-specific timeout and buffering values. Those settings are not universal defaults: select them after identifying the application’s request durations, payload sizes, and public URL scheme.

When Nginx terminates TLS, make sure CherryPy’s proxy-aware base URL represents the HTTPS hostname users see. Otherwise generated links or redirects can point to the wrong scheme. Test normal pages, redirects, uploaded bodies, and long-running requests after applying any timeout or buffering policy.

Access-control rules and health checks also depend on your deployment. Restrict the CherryPy listener to the intended private interface, decide which networks may reach Nginx, and add active health checks only when their behavior and failure thresholds are understood. The cited baseline does not prescribe values for these options.

WebSockets require an explicit upgrade path

CherryPy’s advanced documentation identifies the external ws4py library as the source of WebSocket support. A WebSocket application therefore needs end-to-end upgrade handling in Nginx in addition to the ordinary HTTP proxy baseline. Do not assume that a configuration that serves pages and JSON automatically supports WebSocket handshakes.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Test the upgrade request through the public hostname, verify that the application receives the upgraded connection, and confirm that idle and application-specific timeouts do not terminate it unexpectedly. Add the required upgrade headers and timeout policy only after deciding that the application actually uses WebSockets; they are unnecessary for a conventional HTTP-only site.

Troubleshoot by isolating the failing hop

The local CherryPy request fails

  • Check that the process is running and bound to the port named in the upstream.
  • Confirm that the application’s global configuration uses the intended server.socket_port.
  • If using uWSGI, verify that CherryPy’s built-in server is disabled and that the uWSGI command names the correct WSGI file and callable.

The local request works but the public request fails

  • Run the Nginx configuration test and fix syntax, hostname, or path errors.
  • Compare proxy_pass with the actual listener protocol and port.
  • Inspect Nginx and CherryPy logs together to determine whether the request reached the upstream.
  • Confirm that the request’s hostname matches server_name and that DNS or the local test host resolves it to Nginx.

The application sees the wrong host or client address

  • Check all four forwarding directives in the proxy location.
  • Ensure tools.proxy.on is enabled in CherryPy.
  • Set tools.proxy.base to the public hostname and scheme rather than the private port.
  • Inspect application logs for the received host and forwarded address values.

Static files return errors while dynamic routes work

  • Verify the root directory and the URL-to-file mapping for the /static/ location.
  • Check read permissions for the Nginx worker account.
  • Request an exact known filename and compare it with the path on disk.

One of two instances behaves differently

  • Request each local port directly and compare application versions and configuration.
  • Stop one process briefly to confirm which upstream receives requests and how failures are logged.
  • Restore the process and remove stale or incorrectly configured listeners from the upstream block.

Operational checklist

  • CherryPy responds on its private listener before Nginx is introduced.
  • The upstream addresses and protocol match the selected process model.
  • The public server_name matches CherryPy’s proxy base URL.
  • Host, X-Real-IP, X-Forwarded-For, and X-Forwarded-Host are forwarded.
  • CherryPy’s proxy tool is enabled when public URL or original-client metadata is required.
  • The Nginx configuration passes its syntax test before reload.
  • Dynamic routes and /static/ paths are tested separately.
  • Every configured upstream instance is running, equivalent, and monitored.
  • TLS, redirects, timeouts, buffering, access control, health checks, and WebSocket upgrades are configured only for requirements the application actually has.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More quests from Patch Notes

  1. How to Set Up a RedM (RDR2) Server in 2026: License Key, txAdmin and server.cfg, Step by StepBlog11min
  2. Best RedM (RDR2) Server Hosting in 2026: Comparing Four Hosts on Slots, Memory and PriceBlog10min
  3. How to Host a Mindustry Server in 2026: server-release.jar, Port 6567 and the Commands That MatterBlog7min
Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.