FlashPanel

Deploy a Python (Flask) application ​

Suppose you have a Flask application that you want to run under the domain app.domain.com. The application runs with Gunicorn (a production WSGI HTTP server that handles concurrency better than Flask's built-in server) on port 8000, Supervisor keeps Gunicorn running, and the website on FlashPanel forwards requests for the domain to port 8000.

Prerequisites ​

  • Server connected to FlashPanel
  • Domain DNS pointed to the server's IP
  • Your source code has a requirements.txt file listing the packages to install

INFO

FlashPanel installs python3 and pip when the server is connected, so the Apps page has no separate Python entry.

Step 1: Install Python venv ​

Open Terminal on the server's overview page (logged in as root) and run the command below. You only need to do this once per server:

bash
apt install -y python3-venv

Step 2: Create a Website ​

  1. Go to the server management page, click the Sites menu in the sidebar, then click the New Site button
  2. Enter the Domain Name (e.g., app.domain.com)
  3. Enter the Proxy Port: 8000 (the port Gunicorn will listen on)
  4. Click Create Site

TIP

If you enable Website Isolation, the website runs as its own Linux user. In that case, replace flashpanel in the paths below with the website's isolation username.

Step 3: Upload the Source Code ​

Choose one of the following:

  • From Git (recommended): on the site management page, click the Install Source Code menu and install your repository. See Source Code Installation.
  • Upload it yourself: open File Manager on the website's overview page and upload your code to the website directory. See File Manager.

The source code lives in /home/flashpanel/app.domain.com.

Step 4: Create a Virtual Environment and Install Dependencies ​

Open Terminal on the website's overview page (the terminal logs in as the user that owns the website and opens the website directory), then run:

bash
cd /home/flashpanel/app.domain.com

# Create and activate the virtual environment
python3 -m venv venv
source venv/bin/activate

# Install your application's dependencies and Gunicorn
pip install -r requirements.txt
pip install gunicorn

Run a quick test to make sure the application works, then press Ctrl+C to stop it:

bash
gunicorn --bind 127.0.0.1:8000 app:app

In app:app, the part before : is the Python file that contains the application (app.py), and the part after it is the name of the Flask application variable in that file (app = Flask(__name__)). Adjust both to match your project. For Django, use the form your_project.wsgi:application.

TIP

--bind 127.0.0.1:8000 makes Gunicorn listen only on the server itself. Requests from the Internet go through the website (domain), and port 8000 is not exposed. Do not use 0.0.0.0 unless you really need direct access by IP and port.

Step 5: Run Gunicorn in the Background with Supervisor ​

Use Supervisor to keep Gunicorn running in the background and restart it automatically when it stops or the server reboots:

  1. Go to the server management page, click the Supervisor menu, then click the Create button
  2. In the New Supervisor dialog, fill in:
    • Description (Optional): e.g., app.domain.com gunicorn
    • Command: /home/flashpanel/app.domain.com/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
    • User: the user that owns the website (flashpanel by default)
    • Directory (Optional): /home/flashpanel/app.domain.com
    • Keep Number Processes at 1 (Gunicorn manages its own workers)
  3. Click Save

Note the value in the ID column of the new process (for example 5); you need it to restart the process from the command line.

TIP

--workers 3 is the number of Gunicorn worker processes running in parallel. A common value is 2 × CPU cores + 1.

Step 6: Install SSL ​

On the site management page, click the SSL menu and install a certificate for the domain. See SSL.

Step 7: Set Up Deployment Script (Optional) ​

If the source code was installed from Git, go to the site management page, click the Deployments menu, edit the Deploy Script section, then click Update. For example (replace 5 with the ID of the Supervisor process):

bash
cd /home/flashpanel/app.domain.com
git pull origin main
venv/bin/pip install -r requirements.txt
sudo supervisorctl restart daemon-5:*

WARNING

The sudo supervisorctl command only works when the website uses the default user flashpanel. For websites with Website Isolation enabled, remove the last line and restart the process on the Supervisor page after each deployment.

Verify the Result ​

  1. On the Supervisor page, the new process shows as running
  2. Visit https://app.domain.com and check that your application responds correctly

Updating the Application ​

  • If you have configured a Deployment Script, click Deploy Now in the Deployments menu of the website
  • If you upload code manually, run venv/bin/pip install -r requirements.txt again after uploading the new version (if dependencies changed), then on the Supervisor page click the arrow icon at the end of the process row and choose Restart

Troubleshooting ​

Application Won't Start ​

  1. On the Supervisor page, open the process's action menu and choose Show Log
  2. Activate the virtual environment and run the application manually in the website directory to see the error: source venv/bin/activate && gunicorn --bind 127.0.0.1:8000 app:app
  3. Check that the path to venv/bin/gunicorn and the app:app part in Command are correct

502 Bad Gateway ​

  1. Check that the Supervisor process is running
  2. Make sure the port in --bind matches the website's Proxy Port
  3. See also 502 Bad Gateway

ModuleNotFoundError ​

The package is not installed in the virtual environment. Run venv/bin/pip install -r requirements.txt in the website directory, then restart the process.