Lecture 6: Couchbase Server & Varnish Cache

Couchbase Server Setup and Architecture

Welcome to our exploration of Couchbase Server, a tool that often blurs the line between a traditional database and a high-performance cache. Unlike simpler key-value stores like Redis or Memcached, Couchbase is a full-featured, distributed NoSQL document database built with a "memory-first" architecture. This design makes it exceptionally fast for read and write operations, positioning it as a powerful solution for complex caching scenarios, session management, and even as a primary data store (Couchbase, Inc., 2023).

Core Architectural Concepts

To effectively use Couchbase, you must understand its fundamental components. It’s more than just a key-value store; it’s a distributed system designed for scalability and high availability.

• Nodes and Clusters: A Couchbase deployment consists of one or more servers, called nodes. Multiple nodes work together in a group called a cluster. Even a single-server deployment is technically a cluster of one node. This cluster-based design is key to its scalability—you can add more nodes to the cluster to increase capacity and performance linearly.
• Services: Couchbase employs a Multi-Dimensional Scaling (MDS) architecture. This means you can assign different roles, or services, to different nodes in the cluster. This allows for fine-grained resource allocation. The core services include:
  • Data Service: Manages the storage and retrieval of data (key-value operations). This is the heart of the caching functionality.
  • Query Service: Parses and executes N1QL (SQL-like) queries against your JSON documents.
  • Index Service: Creates and manages indexes to speed up N1QL queries. It's essential for any query-heavy workload.
  • Search, Analytics, Eventing: More advanced services for full-text search, complex analytical queries, and server-side business logic, respectively. For a pure caching use case, these are often disabled to conserve resources.
• Buckets: A bucket is a logical container for your data, analogous to a database in a relational system. You can create multiple buckets within a cluster, each with its own resource allocation (RAM quota), replica count, and eviction policy. For session caching, you might create a dedicated `user_sessions` bucket.
• vBuckets (Virtual Buckets): This is Couchbase's sharding mechanism. Each bucket is divided into 1024 logical partitions called vBuckets. These vBuckets are then distributed evenly across the data nodes in the cluster. When you perform an operation on a key, Couchbase uses a hashing algorithm to determine which vBucket the key belongs to, and thus which node is responsible for it. This ensures an even data distribution and allows the cluster to rebalance automatically when nodes are added or removed.

Hardware Requirements

Couchbase is more resource-intensive than lightweight caches due to its powerful feature set and Java-based architecture. For a small, on-premise installation focused on session caching for a handful of users, the minimum requirements are manageable but notable (Jainandunsing, 2025).

• CPU: 2 cores (Intel/AMD @ 2.0+ GHz or better)
• RAM: 4 GB (2 GB for Couchbase services, 2 GB for the operating system)
• Storage: 20 GB SSD (for logs, binaries, and potential disk persistence)
• Network: 1 Gbps Ethernet

The 4 GB RAM requirement is critical. Couchbase's performance stems from its ability to hold the "working set" of data in memory. The operating system also requires a significant amount of memory to function smoothly, so allocating at least 2 GB for Couchbase itself and 2 GB for the OS is a safe starting point.

Installation and Configuration on Ubuntu

Let's walk through the process of setting up Couchbase Server Community Edition on an Ubuntu server. These steps prepare your system and install the software from Couchbase's official repository.

1. Update System and Install Dependencies: First, ensure your system is up-to-date and has the necessary tools like `curl` and `gnupg2`.

   sudo apt update && sudo apt upgrade -y
   sudo apt install curl gnupg2 lsb-release -y

2. Add the Couchbase Repository: You need to add Couchbase's package repository to your system's sources to install the server. This involves downloading their GPG key to verify the package authenticity and then adding the repository URL.

   wget https://packages.couchbase.com/ubuntu/couchbase.key
   sudo apt-key add couchbase.key
   CODENAME=$(lsb_release -cs)
   echo "deb https://packages.couchbase.com/ubuntu ${CODENAME} main" | sudo tee /etc/apt/sources.list.d/couchbase.list

3. Install Couchbase Server: With the repository added, you can now update your package list again and install the `couchbase-server-community` package.

   sudo apt update
   sudo apt install couchbase-server-community -y

After installation, the Couchbase service starts automatically. The next steps involve configuring the cluster through its user-friendly web console.

Initial Setup via Web Console

Access the Web UI in your browser at http://<your-server-ip>:8091. You'll be greeted by a setup wizard.

1. Cluster Setup: Create a new cluster. Give it a name (e.g., `SessionCluster`), and create an administrator account with a strong password.
2. Services: For a caching-focused setup, you only need the Data service. You can also enable the Query and Index services if you plan to query the session data using N1QL, but they can be skipped to minimize RAM usage. Uncheck Search, Analytics, and Eventing.
3. RAM Quotas: This is a crucial step. You'll set the total RAM available to the Data service for this node. For our minimum spec machine with 4 GB total RAM, a conservative value is 1024 MB (1 GB), leaving plenty for the OS and other services (Jainandunsing, 2025).
4. Create a Bucket: This will be the container for your session data.
   • Name: `user_sessions`
   • Type: Couchbase (provides persistence options) or Ephemeral (in-memory only, faster, ideal for pure caching). Let's choose Couchbase for flexibility.
   • Bucket RAM Quota: Allocate a portion of the service's RAM to this bucket, for example, 512 MB.
   • Eviction Policy: This determines what happens when the bucket's RAM is full. Value Ejection evicts only the value of a key-value pair, keeping the key and metadata in memory. This is faster for lookups where the item is not found. Full Ejection evicts the key, value, and all metadata, freeing up more memory but making lookups for non-existent items slower. For session caching, Value Ejection is often preferred.
   • Enable TTL: This is vital. Check this box to enable Time-To-Live on documents. You can set a default TTL for the entire bucket, for example, 3600 seconds (1 hour). This ensures old sessions are automatically purged.

Optimizing for Caching Behavior

While Couchbase has a persistent storage engine, you can configure it to behave like a pure in-memory cache. With an Ephemeral bucket, this is the default. With a Couchbase bucket, the primary strategy is to rely on aggressive TTLs and the memory manager. By setting a short TTL on all session documents, you ensure they expire and are removed from memory without ever needing to be written to disk in a meaningful way. In the bucket settings, you can also set the number of replicas to 0 if you are running a single-node cluster and don't need data redundancy, further reducing overhead.

Varnish Cache: The HTTP Accelerator

Shifting gears dramatically, we now turn to Varnish Cache. If Couchbase is a versatile database that can cache, Varnish is a highly specialized tool built for one purpose: to make your web applications fly. Varnish is a reverse proxy HTTP accelerator. It sits in front of your web server (like Apache or NGINX) and caches the responses it generates. The next time the same request comes in, Varnish serves the cached copy directly from memory without ever bothering your backend server. This can result in performance improvements of several orders of magnitude (Kamp, 2010).

It's critical to understand that Varnish works at the HTTP layer. It caches entire HTTP responses—headers and body included. It is not a general-purpose object cache. As Jainandunsing (2025) notes, it's "best used for caching HTTP content, API responses, or web pages — not typically for user session data." We'll see how to make it *aware* of sessions, but it won't *store* them.

Varnish Architecture

• The `varnishd` Daemon: This is the main Varnish process. It has two main parts: the master process, which manages the child process, and the child process (or cache process), which does all the work of accepting connections and serving content. This design allows for seamless configuration reloads without dropping client connections.
• VCL (Varnish Configuration Language): This is the heart of Varnish's power and flexibility. VCL is a domain-specific language that gets translated into C code, compiled into a shared library, and loaded directly by `varnishd`. This is a key reason for its incredible speed. You write VCL code to control how requests are handled.
• Shared Memory Log (`varnishlog`): Varnish logs an immense amount of data to a shared memory segment. Tools like `varnishlog`, `varnishstat`, and `varnishtop` can be used to tap into this log in real-time to debug and monitor the cache's performance with granular detail.

The VCL State Machine

Understanding the request lifecycle in Varnish is crucial. A request flows through a series of VCL subroutines, which you can customize. The most important ones are:

1. `vcl_recv` (Receive): This is the first stop for a new request. It's where you decide what to do. You can modify the request, look for cookies, and decide whether to serve from cache (`hash`), fetch from the backend (`pass`), or throw an error (`error`).
2. `vcl_hash` (Hash): If `vcl_recv` returns `hash` (the default), this subroutine creates a hash key based on the request URL and host. This hash is used to look up the object in the cache.
3. `vcl_hit` / `vcl_miss` (Hit/Miss): If the object is found in cache, `vcl_hit` is called. If not, `vcl_miss` is called. In `vcl_miss`, the request is typically sent to the backend.
4. `vcl_backend_fetch` (Fetch): This is called just before sending the request to the backend server. You can modify the request being sent to the backend here.
5. `vcl_backend_response` (Backend Response): After the backend sends a response, this subroutine is executed. Here you can modify the response from the backend before it's stored in the cache. This is a great place to set the TTL of the object and strip any user-specific cookies.
6. `vcl_deliver` (Deliver): This is the last stop before the response is sent to the client. You can modify the final response headers here (e.g., add debugging headers).

Hardware Requirements

Varnish is exceptionally lightweight, a direct result of its focused design and C implementation.

• CPU: 1 core @ 2.0+ GHz
• RAM: 512 MB – 1 GB (most of this is for the in-memory cache itself)
• Storage: 5 GB SSD (for logs and binaries only, as Varnish is in-memory by default)
• Network: 1 Gbps NIC

This minimal footprint makes Varnish suitable for running on small virtual machines or even alongside your web server on the same machine for smaller applications (Jainandunsing, 2025).

Installation and Configuration on Ubuntu

Setting up Varnish is straightforward.

1. Install Varnish: The package is available in the default Ubuntu repositories.

   sudo apt update
   sudo apt install varnish -y

2. Configure the Service Port: By default, Varnish listens on port 6081. For a live website, you want it to handle traffic on port 80. You must edit the systemd service file to change this.

   sudo nano /lib/systemd/system/varnish.service

   Find the `ExecStart` line and modify the `-a` parameter. This line also controls how much memory is allocated to the cache via the `-s` parameter (storage engine). Here, we allocate 256 MB.

   ExecStart=/usr/sbin/varnishd \
       -a :80 \
       -T localhost:6082 \
       -f /etc/varnish/default.vcl \
       -s malloc,256m

   After saving the file, you must reload the systemd daemon for the changes to take effect.

   sudo systemctl daemon-reload

3. Configure the Backend: You need to tell Varnish where your actual web application is running. This is done in the main VCL file.

   sudo nano /etc/varnish/default.vcl

   At the top of the file, define your backend. Let's assume your application server is running on the same machine on port 8080.

   backend default {
       .host = "127.0.0.1";
       .port = "8080";
   }

4. Handle User Sessions (Bypass Cache): This is the most critical part for dynamic sites. Varnish should not cache content for logged-in users. The standard way to achieve this is to check for a session cookie in `vcl_recv`. If the cookie exists, we `return (pass)`, which tells Varnish to bypass the cache and send the request directly to the backend.

   sub vcl_recv {
       # Don't cache requests for logged-in users
       if (req.http.Cookie ~ "session_id=") {
           return (pass);
       }
       # Don't cache backend admin areas
       if (req.url ~ "^/admin") {
           return (pass);
       }
       return (hash); # Proceed to cache lookup
   }

5. Restart and Enable Varnish: Finally, restart the service to apply all your changes and enable it to start on boot.

   sudo systemctl restart varnish
   sudo systemctl enable varnish

   You can verify it's working by using `curl -I http://your-server-ip` and looking for headers like `X-Varnish` and `Age`.

Choosing the Right Tool for the Job

We've explored two powerful but fundamentally different caching technologies. Couchbase Server is a data-centric, application-layer cache and database. Varnish Cache is a network-centric, HTTP-layer cache. Understanding their distinct strengths and weaknesses is crucial for designing an efficient and scalable system architecture. Trying to use one for the other's job often leads to complex, inefficient, and brittle solutions.

Direct Comparison: Couchbase vs. Varnish

Use Case 1: User Session Management

• Couchbase Approach: This is an ideal use case for Couchbase. The application server receives a user request, generates a session ID, and stores the associated session data (e.g., user ID, permissions, shopping cart contents) as a JSON document in a Couchbase bucket. The session ID is sent to the client as a cookie. On subsequent requests, the application reads the cookie, fetches the session data from Couchbase, and personalizes the response. This approach is highly scalable, as any application server in a cluster can access the centralized session store.
• Varnish Approach: Varnish is unsuitable for *storing* session data. Its role here is to identify requests that *have* a session and pass them through to the application server without caching. The VCL rule `if (req.http.Cookie ~ "session_id=") { return (pass); }` is the classic implementation. Varnish ensures that personalized content is never cached and served to the wrong user, while the actual session management happens in a dedicated store (which could very well be Couchbase!) behind it.

Use Case 2: Caching Public REST API Responses

• Couchbase Approach: This is a "look-aside" caching pattern. An application service needs data from an external, rate-limited API. The logic would be:
  1. Check if the API response is already in a Couchbase bucket using the API endpoint as the key.
  2. If it exists (cache hit), return the data from Couchbase.
  3. If it doesn't exist (cache miss), call the external API, store its response in Couchbase with a TTL, and then return the data.
  This pattern is implemented entirely within the application code and is great for caching arbitrary data, not just HTTP responses.
• Varnish Approach: This is a "transparent" caching pattern. You place Varnish in front of your own API. In the `vcl_backend_response` subroutine, you set a TTL for responses from cacheable endpoints (e.g., `if (bereq.url ~ "^/api/v1/products/") { set beresp.ttl = 5m; }`). Varnish will then automatically cache these responses. This requires no changes to your application code and is extremely efficient for public, non-personalized API endpoints.

Use Case 3: A Hybrid Architecture for a High-Traffic E-commerce Site

The most powerful systems often use both tools together, creating a multi-layered caching strategy that leverages the strengths of each.

1. The Edge Layer (Varnish): Varnish sits at the public-facing edge. Its job is to handle the massive influx of traffic from anonymous users.
   • It performs Full Page Caching (FPC) for product detail pages, category listings, and the homepage. These pages are identical for all anonymous users and can be served from memory at lightning speed.
   • It caches all static assets: images, CSS, and JavaScript files, with very long TTLs.
   • It immediately bypasses the cache for any user with a session cookie or for requests to `/cart`, `/checkout`, or `/account` pages.
2. The Application Layer (Python/Java/PHP App Server): This layer only receives requests that Varnish couldn't handle—typically from logged-in users or for dynamic actions.
3. The Data Cache Layer (Couchbase): The application servers are stateless; all state is managed in Couchbase.
   • Session Management: When a user logs in, their entire session object (including cart contents) is stored in Couchbase.
   • Object Caching: The application caches frequently accessed database query results, such as user profiles, product inventory lookups, or configuration settings. This reduces the load on the primary relational database.
   • Real-time Data: Couchbase can even handle real-time inventory updates or personalized recommendations, providing sub-millisecond latency that a traditional database cannot match.

This hybrid model is incredibly effective. Varnish absorbs the bulk of the traffic (often 80-90%), protecting the application servers. The application servers then rely on Couchbase for high-speed data access for the remaining dynamic requests, protecting the slower, persistent database. This is a classic example of using the right tool for each specific problem in the stack.