---
title: Podman Install
date: 2023/08/18
description: If you don't like docker compose, don't want a bare-metal installation, but still want to leverage the benefits from the isolation and modularity of containers...
tags:
  - install
  - podman
  - guide
ogImage: /images/blog/2023-08-18_podman.png
authorid: anon
---

import { BlogHeader } from '@/components/blog/BlogHeader'

<BlogHeader />

# Podman Installation Guide

If you don't like docker compose, don't want a bare-metal installation, but still want to leverage the benefits from the isolation and modularity of containers - this is the guide you should use.

> Likewise, If you are actively developing LibreChat, aren't using the service productively (i.e production environments), you should avoid this guide and look to something easier to work with such as docker compose.

**Important:** `docker` and `podman` commands are for the most part, interoperable and interchangeable. The code instructions below will use (and heavily favor) `podman`.

##  Creating the base image

Since LibreChat is very active in development, it's recommended for now to build
the image locally for the container you plan on using. Thankfully this is easy enough to do.

In your target directory, run the following:

```bash filename="Clone the LibreChat repository"
git clone https://github.com/danny-avila/LibreChat
```

This will add a directory, `LibreChat` into your local environment.

Without entering the `LibreChat` directory, add a script `./image.sh` with the following:

> If you don't want to run this as a script, you can run the container command rather images

```bash filename="Build the base container image for LibreChat"
podman build --tag "librechat:local" --file ./LibreChat/Dockerfile
```

> Note: the downside of running a base container that has a live root is that image revisions need to be done manually. The easiest way is to remove and recreate the image when the container is no longer. If that's not possible for you, manually updating the image to increment versions can be done manually. Simply amend $image with the version you're building.

> We'll document how to go about the update process more effectively further on. You wont need to remove your existing containers, or lose any data when updating.

## Setting up the env file

Execute the following command to create a env file solely for LibreChat containers:

```bash filename="Copy env.example file to .env"
cp ./LibreChat/.env.example .env
```

This will add the env file to the top level directory that we will create the containers, allowing us to pass it easily as via the `--env-file` command argument.

Follow [this guide](/docs/configuration/pre_configured_ai) to populate the containers with the correct env values for various apis. There are other env values of interest that might be worth changing, documented within the env itself. Afterwords, edit the following lines in the `.env` file.

```sh filename=".env"
HOST=0.0.0.0
MONGO_URI=mongodb://librechat-mongodb:27017/LibreChat
MEILI_HOST=http://librechat-meilisearch:7700
MEILI_NO_ANALYTICS=true
```

These values will be uses by some of our containers to correctly use container DNS, using the LibreChat network.

## Creating a network for LibreChat

If you're going about this the _manual_ way, it's likely safe to assume you're running more than a few different containers and services on your machine. One of the nice features offered by most container engines is that you don't need to have every single container exposed on the host network. This has the added benefit of not exposing your data and dependant services to other containers on your host.

```bash filename="Create a network named librechat using podman"
podman network create librechat
```

We will be using this network when creating our containers.

## Creating dependant containers

LibreChat currently uses mongoDB and meilisearch, so we'll also be creating those containers.

## Mongodb

Install and boot the mongodb container with the following command:

```bash filename="Start mongodb container with network and volume settings"
podman run \
  --name="librechat-mongodb" \
  --network=librechat \
  -v "librechat-mongodb-data:/data/db" \
  --detach \
  docker.io/mongo \
  mongod --noauth
```

## Meilisearch 

Install and boot the melisearch container with the following command:

```bash filename="Install and boot the melisearch container"
podman run \
  --name="librechat-meilisearch" \
  --network=librechat \
  --env-file="./.env" \
  -v "librechat-meilisearch-data:/meili_data" \
  --detach \
  docker.io/getmeili/meilisearch:v1.0;
```

## Starting LibreChat

```bash filename="Start LibreChat"
podman run \
  --name="librechat" \
  --network=librechat \
  --env-file="./.env" \
  -p 3080:3080 \
  --detach \
  librechat:local;
```

If you're using LibreChat behind another load balancer, you can omit the `-p` declaration, you can also attach the container to the same network by adding an additional network argument:

```bash filename="Attach LibreChat to specific network"
--network=librechat \
```

```bash filename="Attach to load balancer network"
--network=mybalancernetwork \
```

As described by the original `-p` command argument, it would be possible to access librechat as `librechat:3080`, `mybalancernetwork` would be replaced with whatever network your balancer exists.

## Auto-starting containers on boot (podman + Linux only)

Podman has a declarative way to ensure that pod starts up automatically on system boot using systemd.

To use this method you need to run the following commands:

First, let's stop any running containers related to LibreChat:

```bash filename="Stop LibreChat container"
podman stop librechat
```

```bash filename="Stop LibreChat MongoDB container"
podman stop librechat-mongodb
```

```bash filename="Stop LibreChat MeiliSearch container"
podman stop librechat-meilisearch
```

Next, we'll update our user's systemd configuration to enable lingering. In systemd-based systems, when a user logs in and out, user-based services typically terminate themselves to save CPU, but since we're using rootless containers (which is podman's preferred way of running), we need to indicate that our user has permission to have user-locked services running after their session ends.

```bash filename="Enable linger for the current user using loginctl"
loginctl enable-linger $(whoami)
```

Next, we'll create a script somewhere in our `home` directory using a text editor. Let's call the script `./install.sh`

```bash filename="./install.sh"
#!/bin/bash
# Install podman container as systemd container
set -e
name="$1";
podman generate systemd --name "$name" > ~/.config/systemd/user/container-$name.service
systemctl --user enable --now container-$name;
```

After saving, we'll update the script to be executable:

```bash filename="Make installation script executable"
chmod +x ./install.sh
```

Assuming we aren't running those LibreChat containers from before, we can enable on-boot services for each of them using the following:

```bash filename="Install Librechat MongoDB"
./install.sh librechat-mongodb 
```

```bash filename="Install Librechat Meilisearch"
./install.sh librechat-meilisearch 
```

```bash filename="Install Librechat Application"
./install.sh librechat 
```

The containers (assuming everything was done to par), will be now running using the systemd layer instead of the podman layer. This means services will load on boot, but also means managing these containers is a little more manual and requires interacting with systemd instead of podman directly.

For instance, instead of `podman stop {name}`, you would instead do `systemctl --user stop container-{name}` to perform maintenance (such as updates or backups). Likewise, if you need to start the service again you simply can run `systemctl --user start container-{name}`. If wanting to use auto-boot functionality, interacting with managed containers using podman can cause issues with systemd's fault tolerance as it can't correctly indicate the state of a container when interfered with.

## Backing up volume containers (podman only)

The podman containers above are using named volumes for persistent data, which means we can't simply copy files from one place to another. This has benefits though. In podman, we can simply backup the volume into a tape archive format (tarball). To do this, run the following commands:

> It's recommended you stop the containers before running these commands.

```bash filename="Backup Librechat Meilisearch Data"
podman volume export librechat-meilisearch-data --output "librechat-meilisearch-backup-$(date +"%d-%m-%Y").tar"
```

```bash filename="Backup Librechat MongoDB Data"
podman volume export librechat-mongodb-data --output "librechat-mongodb-backup-$(date +"%d-%m-%Y").tar"
```

These will leave archive files that you can do what you wish with, including reverting volumes to a previous state if needed. Refer to the **[official podman documentation](https://docs.podman.io/en/latest/markdown/podman-volume-import.1.html)** for how to do this.

## Updating LibreChat

LibreChat is still under development, so depending on published images isn't a huge viability at the moment. Instead, it's easier to update using git. Data persistence in librechat is managed outside of the main container, so it's rather simple to do an in-place update.

In the parent directory containing the LibreChat repo:

```bash filename="Update Git Repo"
(cd LibreChat && git pull)
```

```bash filename="Stop Systemd Service"
systemctl --user stop container-librechat
```

```bash filename="Remove Librechat Container"
podman rm -f librechat
```

```bash filename="Destroy Local Image"
podman rmi -f librechat:local
```

```bash filename="Rebuild Librechat Image"
podman build --tag "librechat:local" --file ./LibreChat/Dockerfile
```

```bash filename="Recreate Liberchat Container"
podman run --name="librechat" --network=librechat --env-file="./.env" -p 3080:3080 --detach librechat:local
```

```bash filename="Restart Systemd Service After Stopping Container"
podman stop librechat && systemctl --user start container-librechat
```

---

## Integrating the Configuration File in Podman Setup

When using Podman for setting up LibreChat, you can also integrate the [`librechat.yaml` configuration file](/docs/configuration/librechat_yaml).

This file allows you to define specific settings and AI endpoints, such as Mistral AI, tailoring the application to your needs.

After creating your `.env` file as detailed in the previous steps, follow these instructions to integrate the `librechat.yaml` configuration:

1. Place your `librechat.yaml` file in your project's root directory.
2. Modify the Podman run command for the LibreChat container to include a volume argument that maps the `librechat.yaml` file inside the container. This can be done by adding the following line to your Podman run command:

  ```bash filename="Specify Docker Volume Mapping"
  -v "./librechat.yaml:/app/librechat.yaml"
  ```

For example, the modified Podman run command for starting LibreChat will look like this:

It seems like there was a misunderstanding regarding your request as I provided the split commands earlier. To make it into one command, I would combine all the elements into a single command block:

```bash filename="Run Docker Container with Specific Configuration"
docker run --name="librechat" --network=librechat --env-file="./.env" -p 3080:3080 --detach librechat:local
```

By mapping the `librechat.yaml` file into the container, Podman ensures that your custom configurations are applied to LibreChat, enabling a tailored AI experience.

Ensure that the `librechat.yaml` file is correctly formatted and contains valid settings. 

Any errors in this file might affect the functionality of LibreChat. For more information on configuring `librechat.yaml`, refer to the [Custom Endpoints & Configuration](/docs/configuration/librechat_yaml).
