Creating a Gunicorn Systemd Service

1. The Anatomy of a systemd Unit File

In the last lesson, you created /etc/systemd/system/gunicorn.service. This is a systemd unit file. While there are several types of unit files (.socket, .timer, etc.), the .service file is the most common, used to manage daemon processes like Gunicorn.

These files have a clear, structured format using sections (like [Unit]) and directives (like Description=...). To build a solid foundation, let's explore these components in more detail.

To summarize and place this in your Fedora context, systemd looks for unit files in a specific order of priority.

2. A Deeper Look at Our gunicorn.service File

Let's apply that general knowledge to the gunicorn.service file you created. Open it again to follow along: sudo vim /etc/systemd/system/gunicorn.service.

Here is a breakdown of the file, explaining why each line is there.

The [Unit] Section

This section provides metadata about the service and defines its relationship with other systemd units.

• Description=gunicorn daemon: A human-readable description that shows up in systemctl status output.
• Requires=gunicorn.socket: This creates a strong dependency. If gunicorn.socket fails or is stopped, systemd will also stop gunicorn.service. This is exactly what we want in our socket-activated setup.
• After=network.target: This defines the startup order. It ensures that our Gunicorn service only starts after the basic networking stack is up and running.

The [Service] Section

This is the core of the configuration, defining how the service is executed.

• User=your_user & Group=your_user: This is a critical security measure. It ensures your Django application code is run by your non-privileged user account, not as the all-powerful root user. If a vulnerability were ever found in your application, this would significantly limit the potential damage.
• WorkingDirectory=/var/www/myproject: This sets the current working directory before the command is executed. Django and other Python projects often rely on relative paths, and this directive ensures they resolve correctly, no matter where systemd is invoked from.
• ExecStart=...: This is the exact command that systemd runs to start the service. Let's look at it closely:
  • /var/www/myproject/myprojectenv/bin/gunicorn: We use the absolute path to the Gunicorn executable inside our project's virtual environment. This guarantees we are using the correct version of Gunicorn with the correct Python dependencies.
  • --workers 3: This tells Gunicorn to create 3 worker processes to handle requests. A common formula is (2 * CPU cores) + 1. This allows your app to handle multiple requests in parallel.
  • --bind unix:/run/gunicorn.sock: This instructs Gunicorn to listen on the Unix socket file that systemd created for us, not on a TCP port.

The [Install] Section

This section is used when you enable or disable the service.

• WantedBy=multi-user.target: This tells systemd that when you enable this service, it should be part of the "multi-user" target. This is the standard runlevel for a server, meaning your service will be started automatically at boot.

3. Hands-On: Customizing for Robustness

Now for the practical part. Let's make our service more robust and easier to manage, reflecting real-world best practices.

Notice how the ExecStart line can get very long with all the performance-tuning parameters. A cleaner way is to use a separate configuration file for Gunicorn.

Task: Refactor and Enhance gunicorn.service

1. Create a Gunicorn Configuration File:
   First, let's create a Python file to hold our Gunicorn settings. This is much cleaner than a long ExecStart line.

   Create the file inside your project directory:

   
   
   
   
   
   
   # Make sure you are in your project directory
   cd /var/www/myproject
   
   
   
   
   
   
   
   # Create and open the config file
   vim gunicorn_config.py
   

   Paste the following content. It defines the same settings we had before, but in a Python file.

   bind = "unix:/run/gunicorn.sock"
   workers = 3
   

   Save and close the file.

2. Modify the gunicorn.service file:
   Now, let's edit the service file to use our new configuration and add a crucial directive: Restart.

   sudo vim /etc/systemd/system/gunicorn.service
   

   Modify the [Service] section to look like this. Make sure to replace your_user with your actual username.

   [Service]
   User=your_user
   Group=your_user
   WorkingDirectory=/var/www/myproject
   
   
   
   
   
   
   
   # Add this line!
   Restart=on-failure
   
   
   
   
   
   
   
   # Modify this line to use the config file
   ExecStart=/var/www/myproject/myprojectenv/bin/gunicorn \
             --config /var/www/myproject/gunicorn_config.py \
             myproject.wsgi:application
   

   What did we change?

   • Restart=on-failure: This is a powerful feature. It tells systemd to automatically restart the Gunicorn service if it ever exits with an error code. This makes your application self-healing if it crashes for some reason.
   • ExecStart: We replaced the --bind and --workers arguments with a single --config flag pointing to our new gunicorn_config.py file. This is much more organized.

3. Reload systemd and Restart Gunicorn:
   Whenever you change a unit file, you must tell systemd to reload its configuration.

   
   
   
   
   
   
   # Tell systemd to re-read the modified file
   sudo systemctl daemon-reload
   
   
   
   
   
   
   
   # Restart the gunicorn service to apply the changes
   sudo systemctl restart gunicorn.service
   

4. Verify Everything:
   Finally, check the status to ensure your changes were applied and the service is running correctly.

   sudo systemctl status gunicorn.service
   

   You should see active (running), and the service should be running successfully. You can also re-run the curl test from the last lesson to be absolutely sure: curl --unix-socket /run/gunicorn.sock localhost.

Conclusion

Excellent work! You've moved beyond a basic configuration and created a systemd service that is secure, robust, and maintainable—just like you would for a professional deployment.

Key Takeaways:

• A systemd .service file is structured into [Unit], [Service], and [Install] sections, which define what the service is, how it runs, and when it starts.
• Running your application as a non-privileged User is a fundamental security practice.
• The Restart=on-failure directive adds robustness by allowing your service to recover automatically from crashes.
• Using a separate configuration file (e.g., gunicorn_config.py) for your application server keeps your systemd unit file clean and your settings organized.
• You must run sudo systemctl daemon-reload after modifying a unit file for the changes to be recognized.

Preview of the Next Lesson:
We now have Nginx ready to serve static files and a robust Gunicorn service ready to run our Django application. The final piece of the puzzle is to connect them. In the next lesson, we will configure Nginx as a reverse proxy to forward web requests to Gunicorn's socket. We will also tackle the final SELinux permission required to allow Nginx to communicate with that socket.