Skip to content

Commit 5bbe411

Browse files
f1ynf1yn
authored
Add podman installation instructions. Update dockerfile to stub env (danny-avila#819)
* Added podman container installation docs. Updated dockerfile to stub env file if not present in source * Fix typos
1 parent 887fec9 commit 5bbe411

File tree

3 files changed

+229
-7
lines changed

3 files changed

+229
-7
lines changed

‎Dockerfile

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
# Base node image
22
FROM node:19-alpine AS node
33

4-
# Install curl for health check
5-
RUN apk --no-cache add curl
6-
74
COPY . /app
8-
# Install dependencies
95
WORKDIR /app
10-
RUN npm ci
6+
7+
# Install call deps - Install curl for health check
8+
RUN apk --no-cache add curl && \
9+
# We want to inherit env from the container, not the file
10+
# This will preserve any existing env file if it's already in souce
11+
# otherwise it will create a new one
12+
touch .env && \
13+
# Build deps in seperate
14+
npm ci
1115

1216
# React client build
1317
ENV NODE_OPTIONS="--max-old-space-size=2048"

‎docs/install/container_install.md

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
2+
# Container installation guide
3+
4+
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.
5+
6+
> 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.
7+
8+
**Important:** `docker` and `podman` commands are for the most part, interoperable and interchangeable. Since podman should be the better "Libre" choice, code instructions below will use (and heavily favor) `podman` - and some commands will need to be tweaked to compensate for this.
9+
10+
11+
## Creating the base image
12+
13+
Since LibreChat is very active in development, it's recommended for now to build
14+
the image locally for the container you plan on using. Thankfully this is easy enough to do.
15+
16+
In your target directory, run the following:
17+
```bash
18+
git clone https://github.com/danny-avila/LibreChat
19+
```
20+
21+
This will add a directory, `LibreChat` into your local environment.
22+
23+
Without entering the `LibreChat` directory, add a script `./image.sh` with the following:
24+
25+
> If you don't want to run this as a script, you can run the container command rather images
26+
27+
```bash
28+
# Build the base container image (which contains the LibreChat stack - api, client and data providers)
29+
podman build \
30+
--tag "librechat:local" \
31+
--file ./LibreChat/Dockerfile;
32+
```
33+
34+
> Not 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.
35+
36+
> 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.
37+
38+
## Setting up the env file
39+
40+
Execute the following command to create a env file solely for LibreChat containers:
41+
42+
```bash
43+
cp ./LibreChat/.env.example .env
44+
```
45+
46+
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.
47+
48+
Follow [this guide](https://docs.librechat.ai/install/free_ai_apis.html) 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.
49+
50+
```
51+
HOST=0.0.0.0
52+
MONGO_URI=mongodb://librechat-mongodb:27017/LibreChat
53+
MEILI_HOST=http://librechat-meilisearch:7700
54+
MEILI_HTTP_ADDR=librechat-meilisearch:7700
55+
MEILI_NO_ANALYTICS=true
56+
```
57+
58+
These values will be uses by some of our containers to correctly use container DNS, using the LibreChat network.
59+
60+
## Creating a network for LibreChat
61+
62+
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.
63+
64+
```bash
65+
podman network create librechat
66+
```
67+
68+
We will be using this network when creating our containers.
69+
70+
## Creating dependant containers
71+
72+
LibreChat currently uses mongoDB and meilisearch, so we'll also be creating those containers.
73+
74+
## Mongodb
75+
76+
Install and boot the mongodb container with the following command:
77+
78+
```bash
79+
podman run \
80+
--name="librechat-mongodb" \
81+
--network=librechat \
82+
-v "librechat-mongodb-data:/data/db" \
83+
--detach \
84+
docker.io/mongo \
85+
mongod --noauth;
86+
```
87+
88+
## Meilisearch
89+
90+
Install and boot the melisearch container with the following command:
91+
92+
```bash
93+
podman run \
94+
--name="librechat-meilisearch" \
95+
--network=librechat \
96+
--env-file="./.env" \
97+
-v "librechat-meilisearch-data:/meili_data" \
98+
--detach \
99+
docker.io/getmeili/meilisearch:v1.0;
100+
```
101+
102+
## Starting LibreChat
103+
```bash
104+
podman run \
105+
--name="librechat" \
106+
--network=librechat \
107+
--env-file="./.env" \
108+
-p 3080:3080 \
109+
--detach \
110+
librechat:local;
111+
```
112+
113+
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:
114+
115+
```bash
116+
--network=librechat \
117+
--network=mybalancernetwork \
118+
```
119+
120+
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.
121+
122+
## Auto-starting containers on boot (podman + Linux only)
123+
124+
Podman has a declarative way to ensure that pod starts up automatically on system boot using systemd.
125+
126+
To use this method you need to run the following commands:
127+
128+
First, let's stop any running containers related to LibreChat:
129+
s
130+
```bash
131+
podman stop librechat librechat-mongodb librechat-meilisearch
132+
```
133+
134+
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.
135+
136+
```bash
137+
loginctl enable-linger $(whoami)
138+
```
139+
140+
Next, we'll create a script somewhere in our `home` directory using a text editor. Let's call the script `./install.sh`
141+
142+
```bash
143+
#!/bin/bash
144+
# Install podman container as systemd container
145+
set -e
146+
name="$1";
147+
podman generate systemd --name "$name" > ~/.config/systemd/user/container-$name.service
148+
systemctl --user enable --now container-$name;
149+
```
150+
151+
After saving, we'll update the script to be executable:
152+
153+
```bash
154+
chmod +x ./install.sh
155+
```
156+
157+
Assuming we aren't running those LibreChat containers from before, we can enable on-boot services for each of them using the following:
158+
159+
```bash
160+
./install.sh librechat-mongodb
161+
./install.sh librechat-meilisearch
162+
./install.sh librechat
163+
```
164+
165+
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.
166+
167+
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.
168+
169+
## Backing up volume containers (podman only)
170+
171+
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:
172+
173+
> It's recommended you stop the containers before running these commands.
174+
175+
```bash
176+
# backup the
177+
podman volume export librechat-meilisearch-data --output "librechat-meilisearch-backup-$(date +"%d-%m-%Y").tar"
178+
podman volume export librechat-mongodb-data --output "librechat-mongodb-backup-$(date +"%d-%m-%Y").tar"
179+
```
180+
181+
These will leave archive files that you can do what you wish with, including reverting volumes to a previous state if needed. Refer to [podman documentation](https://docs.podman.io/en/latest/markdown/podman-volume-import.1.html) for how to do this.
182+
183+
## Updating LibreChat
184+
185+
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.
186+
187+
In the parent directory containing the LibreChat repo:
188+
189+
```bash
190+
# Update the git repo
191+
(cd LibreChat && git pull);
192+
193+
# (ONLY if using systemd auto start) Stop the service
194+
systemctl --user stop container-librechat
195+
196+
# Remove the librechat container
197+
podman rm -f librechat
198+
199+
# Destroy the local image
200+
podman rmi -f librechat:local
201+
202+
# Rebuild the image
203+
podman build \
204+
--tag "librechat:local" \
205+
--file ./LibreChat/Dockerfile;
206+
207+
# Recreate the container (using the Starting LibreChat step)
208+
podman run \
209+
--name="librechat" \
210+
--network=librechat \
211+
--env-file="./.env" \
212+
-p 3080:3080 \
213+
--detach \
214+
librechat:local;
215+
216+
# Stop the container (if it's confirmed to be running) and restart the service
217+
podman stop librechat && systemctl --user start container-librechat
218+
```

‎docs/install/docker_install.md renamed to ‎docs/install/docker_compose_install.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Docker Installation Guide
1+
# Docker Compose Installation Guide
22

3-
Docker installation is recommended for most use cases. It's the easiest, simplest, and most reliable method to get started.
3+
Docker Compose installation is recommended for most use cases. It's the easiest, simplest, and most reliable method to get started.
44

55
See the video guide for [Windows](windows_install.md#recommended) or [Ubuntu 22.04 LTS](linux_install.md#recommended)
66
## Installation and Configuration

0 commit comments

Comments
 (0)