LocalAI Web UI Broken Behind TLS Reverse Proxy: How To Fix

by Admin 59 views
LocalAI Web UI Broken Behind TLS Reverse Proxy: How to Fix

Hey guys! Having trouble with your LocalAI Web UI when it's behind a TLS termination reverse proxy? You're not alone! This article will dive into the issue, explore the causes, and provide you with a step-by-step guide to get things up and running smoothly. We'll cover everything from identifying the problem to implementing solutions, ensuring your LocalAI setup is both secure and functional. So, let's get started and tackle this head-on!

Understanding the Issue

So, you've set up LocalAI behind a TLS termination reverse proxy, and the Web UI is looking like a jumbled mess? You're seeing weird graphical glitches, elements not loading correctly, or the whole thing just looks…off? This is a common problem, and it usually boils down to how the Web UI assets are being loaded and served when TLS is involved. Let's break down what's happening under the hood.

The Role of TLS Termination

First off, let's talk about TLS termination. In simple terms, it's like having a bodyguard for your server. The reverse proxy (like HAProxy or Apache) handles the SSL/TLS encryption and decryption, so your LocalAI server doesn't have to. This is great for performance and security, as it offloads the heavy lifting from your application server. However, this setup can sometimes introduce complexities, especially when dealing with web applications that load assets from different paths or need to be aware of the secure context.

Why the Web UI Breaks

The main culprit behind a broken Web UI in this scenario is often mismatched protocols and paths. Your browser is making requests over HTTPS (the secure version of HTTP), but if the Web UI isn't correctly configured to serve assets over HTTPS or if the paths are messed up due to the reverse proxy, things can go south quickly. Think of it like this: the browser expects a secure handshake, but the server is responding in plain text or with incorrect directions. This leads to the browser refusing to load certain resources, resulting in the UI looking broken.

Common Symptoms

Before we dive into the fixes, let's make sure we're on the same page about the symptoms. You might encounter these issues:

  • Missing Styles: The Web UI looks like plain HTML, without any CSS styling. This is a classic sign of CSS files not being loaded correctly.
  • Broken Images: Images are not displaying, often showing a broken image icon.
  • JavaScript Errors: JavaScript files are failing to load or execute, leading to interactive elements not working.
  • Console Errors: Your browser's developer console will likely be filled with errors related to mixed content (HTTP content being loaded over HTTPS) or failed resource requests.

The Importance of Correct Configuration

To sum it up, the key to fixing a broken Web UI behind a TLS termination reverse proxy lies in correct configuration. We need to ensure that the reverse proxy is properly forwarding requests, that LocalAI is aware it's running behind a proxy, and that all assets are served over HTTPS with the correct paths. It's like making sure all the ingredients are not only present but also mixed in the right proportions for the perfect recipe. Now, let's get cooking and see how we can fix this!

Diagnosing the Problem

Okay, so your LocalAI Web UI is acting up behind a TLS reverse proxy. Before we jump into solutions, let's put on our detective hats and figure out exactly what's going wrong. A little diagnosis can save a lot of headaches later. Think of it like going to the doctor – you need to describe your symptoms before you can get the right treatment.

Using the Browser Developer Tools

Your best friend in this situation is the browser developer tools. Almost every modern browser (Chrome, Firefox, Safari, Edge) comes with a built-in suite of tools that let you inspect network requests, console logs, and more. To access them, usually, you can right-click on the page and select "Inspect" or "Inspect Element," or you can use keyboard shortcuts like Ctrl+Shift+I (or Cmd+Option+I on macOS).

Once you've opened the developer tools, you'll want to focus on a few key areas:

  • Network Tab: This tab shows you all the requests your browser is making, including the status codes (200 OK, 404 Not Found, etc.), the content type, and the time it took to load. Look for any requests that are failing (status codes 4xx or 5xx) or taking a long time to load. Pay close attention to requests for CSS, JavaScript, and image files – these are often the culprits.
  • Console Tab: This tab displays any errors or warnings that the browser encounters while loading the page. You might see messages about mixed content (loading HTTP resources over HTTPS), failed to load resources, or JavaScript errors. These messages can give you valuable clues about what's going wrong.

Identifying Common Errors

So, what kind of errors should you be looking for? Here are a few common ones:

  • Mixed Content Errors: These errors occur when your page is loaded over HTTPS, but it's trying to load resources (like CSS or JavaScript) over HTTP. Browsers will often block these requests for security reasons. The error message might say something like "Mixed Content: The page at 'https://your-localai-domain.com' was loaded over HTTPS, but requested an insecure resource 'http://your-localai-domain.com/style.css'."
  • 404 Not Found Errors: These errors mean that the browser couldn't find the requested resource. This could be due to incorrect paths in your HTML or reverse proxy configuration issues. Check the URL in the error message and make sure it's correct.
  • CORS Errors: Cross-Origin Resource Sharing (CORS) errors occur when a web page tries to make a request to a different domain than the one that served the page. This is a security mechanism to prevent malicious websites from accessing your data. If you see CORS errors, you might need to configure your reverse proxy to allow cross-origin requests.

Analyzing the Logs

Don't forget to check the logs for both your reverse proxy (HAProxy, Apache, etc.) and LocalAI itself. The logs can provide valuable insights into what's happening behind the scenes. Look for error messages, warnings, or anything that seems out of the ordinary. For example, if you're using HAProxy, you can check the logs using sudo journalctl -u haproxy.

Checklist for Diagnosis

Before moving on to solutions, let's run through a quick checklist:

  • [ ] Have you checked the browser developer tools for errors?
  • [ ] Are there any mixed content errors?
  • [ ] Are there any 404 errors for CSS, JavaScript, or image files?
  • [ ] Are there any CORS errors?
  • [ ] Have you checked the logs for your reverse proxy and LocalAI?

Once you've answered these questions, you'll have a much clearer picture of what's causing the issue. Now, let's move on to the fun part: fixing it!

Implementing Solutions

Alright, detective work done! Now it's time to roll up our sleeves and fix this LocalAI Web UI issue. We've identified the problem, now let's implement the solutions. Remember, there's no one-size-fits-all answer, so we'll go through several common fixes. Think of it as having a toolbox full of different tools – you'll need to choose the right one for the job.

1. Configuring the Reverse Proxy

The first place to look is your reverse proxy configuration. Whether you're using HAProxy, Nginx, Apache, or something else, the key is to make sure it's correctly forwarding requests and handling TLS termination. Let's break down some common configurations.

HAProxy Configuration

If you're using HAProxy, here's a basic configuration snippet that you might need to adjust:

frontend local-ai
    mode tcp
    bind *:8081 ssl crt /etc/haproxy/tls/
    use_backend local-ai

backend local-ai
    server local-ai localhost:8080

Make sure that:

  • The bind directive is using ssl to indicate TLS termination.
  • The crt directive points to the correct path for your certificate and key.
  • The server directive is pointing to the correct address and port for your LocalAI instance.

For Web UI issues, you might need to add HTTP mode configuration to handle headers correctly. Here’s an example:

frontend local-ai
    mode http
    bind *:8081 ssl crt /etc/haproxy/tls/
    use_backend local-ai

backend local-ai
    mode http
    server local-ai localhost:8080
    http-request add-header X-Forwarded-Proto https if { ssl_fc }

This configuration ensures that the X-Forwarded-Proto header is set to https when the connection to HAProxy is secure. This is crucial for LocalAI to understand that it’s running behind a TLS proxy.

Nginx Configuration

For Nginx, a typical configuration might look like this:

server {
    listen 8081 ssl;
    server_name your-localai-domain.com;

    ssl_certificate /etc/nginx/tls/your-certificate.crt;
    ssl_certificate_key /etc/nginx/tls/your-certificate.key;

    location / {
        proxy_pass http://localhost:8080;
        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-Proto $scheme;
    }
}

The key directives here are:

  • listen specifies the port and that it's using SSL.
  • ssl_certificate and ssl_certificate_key point to your certificate and key.
  • proxy_pass forwards requests to your LocalAI instance.
  • proxy_set_header directives are crucial for passing information about the original request to LocalAI, including the protocol (X-Forwarded-Proto).

Apache Configuration

If you're using Apache, you'll need to enable the mod_proxy, mod_proxy_http, and mod_ssl modules. A basic virtual host configuration might look like this:

<VirtualHost *:8081>
    ServerName your-localai-domain.com

    SSLEngine on
    SSLCertificateFile /etc/apache2/tls/your-certificate.crt
    SSLCertificateKeyFile /etc/apache2/tls/your-certificate.key

    <Proxy *> 
        Require all granted
    </Proxy>

    ProxyPass / http://localhost:8080/
    ProxyPassReverse /	http://localhost:8080/

    RequestHeader set X-Forwarded-Proto "https"

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Key points to note:

  • SSLEngine on enables SSL.
  • SSLCertificateFile and SSLCertificateKeyFile point to your certificate and key.
  • ProxyPass and ProxyPassReverse forward requests to LocalAI.
  • `RequestHeader set X-Forwarded-Proto