Skip to content

Commit eab4df6

Browse files
mrcfpsmrcfps
authored
Merge pull request #1 from refly-ai/docs/self-deploy-guide
Docs/self deploy guide
2 parents 30b5a06 + db86864 commit eab4df6

File tree

6 files changed

+955
-1096
lines changed

6 files changed

+955
-1096
lines changed

Diff for: ‎.vitepress/config.ts

+10-2
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,11 @@ const sidebar = {
2828
en: [
2929
{
3030
text: "Guide",
31-
items: [{ text: "Getting Started", link: "/guide/getting-started" }],
31+
items: [
32+
{ text: "Getting Started", link: "/guide/getting-started" },
33+
{ text: "Self-Deploy", link: "/guide/self-deploy" },
34+
{ text: 'Configuration', link: '/guide/configuration'}
35+
],
3236
},
3337
{
3438
text: "Community",
@@ -57,7 +61,11 @@ const sidebar = {
5761
zh: [
5862
{
5963
text: "指南",
60-
items: [{ text: "快速开始", link: "/zh/guide/getting-started" }],
64+
items: [
65+
{ text: "快速开始", link: "/zh/guide/getting-started" },
66+
{ text: "自主部署", link: "/zh/guide/self-deploy" },
67+
{ text: "配置", link: "/zh/guide/configuration" },
68+
],
6169
},
6270
{
6371
text: "社区",

Diff for: ‎guide/configuration.md

+230
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# Configuration
2+
3+
## API Server
4+
5+
The following are the detailed configurations for the API server. You can inject these environment variables into the `refly_api` container.
6+
7+
### General Config
8+
9+
| Env | Description | Default Value |
10+
| --- | --- | --- |
11+
| NODE_ENV | Node environment | `development` |
12+
| PORT | HTTP API service port, used for regular API requests | `5800` |
13+
| WS_PORT | WebSocket server port, used for real-time synchronization for canvases and documents | `5801` |
14+
| ORIGIN | Client origin (where you are accessing the Refly application from), used for CORS check | `http://localhost:5700` |
15+
| STATIC_ENDPOINT | Static file endpoint, used for serving static files | `http://localhost:5800/v1/misc/` |
16+
17+
### Credentials
18+
19+
| Env | Description | Default Value |
20+
| --- | --- | --- |
21+
| OPENAI_API_KEY | [OpenAI](https://openai.com/) API key, used for LLM inference and embeddings | (not set) |
22+
| OPENROUTER_API_KEY | [OpenRouter](https://openrouter.ai/) API key, used for LLM inference | (not set) |
23+
| JINA_API_KEY | [Jina](https://jina.ai/) API key, used for embeddings | (not set) |
24+
| FIREWORKS_API_KEY | [Fireworks](https://fireworks.ai/) API key, used for embedding | (not set) |
25+
| SERPER_API_KEY | [Serper](https://serper.dev/) API key, used for online search | (not set) |
26+
27+
### Middlewares
28+
29+
Refly depends on following middlewares to function properly:
30+
31+
- **Postgres**: used for basic data persistence
32+
- **Redis**: used for cache, asynchronous task queue and coordination within distributed environment
33+
- **Qdrant**: used for semantic searching via embeddings
34+
- **Elasticsearch**: used for full-text searching within workspace
35+
- **MinIO**: used for object storage for canvas, document and resource data
36+
37+
#### Postgres
38+
39+
| Env | Description | Default Value |
40+
| --- | --- | --- |
41+
| DATABASE_URL | PostgreSQL connection URL | `postgresql://refly:test@localhost:5432/refly?schema=refly` |
42+
43+
::: info
44+
Refer to [Prisma doc](https://www.prisma.io/docs/orm/overview/databases/postgresql#connection-details) for detailed definition of connection URL.
45+
:::
46+
47+
#### Redis
48+
49+
| Env | Description | Default Value |
50+
| --- | --- | --- |
51+
| REDIS_HOST | Redis host | `localhost` |
52+
| REDIS_PORT | Redis port | `6379` |
53+
| REDIS_PASSWORD | Redis password | `test` |
54+
55+
#### Qdrant (Vector Store)
56+
57+
| Env | Description | Default Value |
58+
| --- | --- | --- |
59+
| QDRANT_HOST | Qdrant host | `localhost` |
60+
| QDRANT_PORT | Qdrant port | `6333` |
61+
| QDRANT_API_KEY | Qdrant API key | (not set) |
62+
| REFLY_VEC_DIM | Vector dimension size | `768` |
63+
64+
#### Elasticsearch
65+
66+
| Env | Description | Default Value |
67+
| --- | --- | --- |
68+
| ELASTICSEARCH_URL | Elasticsearch URL | `http://localhost:9200` |
69+
| ELASTICSEARCH_USERNAME | Elasticsearch username | (not set) |
70+
| ELASTICSEARCH_PASSWORD | Elasticsearch username | (not set) |
71+
72+
#### MinIO
73+
74+
Refly requires two MinIO instances:
75+
76+
- **Internal**: used for storing canvas, resource, and document data, typically with visibility set to *private*.
77+
- **External**: used for storing uploaded files, typically with visibility set to *public*.
78+
79+
| Env | Description | Default Value |
80+
| --- | --- | --- |
81+
| MINIO_INTERNAL_ENDPOINT | MinIO host used for internal data | `localhost` |
82+
| MINIO_INTERNAL_PORT | MinIO port used for internal data | `9000` |
83+
| MINIO_INTERNAL_USE_SSL | Whether to use HTTPS for transport | `false` |
84+
| MINIO_INTERNAL_ACCESS_KEY | Access key for internal MinIO | `minioadmin` |
85+
| MINIO_INTERNAL_SECRET_KEY | Secret key for MinIO | `minioadmin` |
86+
| MINIO_INTERNAL_BUCKET | Bucket name for internal | `refly-weblink` |
87+
| MINIO_EXTERNAL_ENDPOINT | MinIO host used for internal data | `localhost` |
88+
| MINIO_EXTERNAL_PORT | MinIO port used for internal data | `9000` |
89+
| MINIO_EXTERNAL_USE_SSL | Whether to use HTTPS for transport | `false` |
90+
| MINIO_EXTERNAL_ACCESS_KEY | Access key for internal MinIO | `minioadmin` |
91+
| MINIO_EXTERNAL_SECRET_KEY | Secret key for MinIO | `minioadmin` |
92+
| MINIO_EXTERNAL_BUCKET | Bucket name for internal | `refly-weblink` |
93+
94+
### Authentication Configuration
95+
96+
| Env | Description | Default Value |
97+
| --- | --- | --- |
98+
| AUTH_SKIP_VERIFICATION | Whether to skip email verification | `false` |
99+
| REFLY_COOKIE_DOMAIN | Cookie domain used for signing authentication tokens | `localhost` |
100+
| LOGIN_REDIRECT_URL | URL to redirect after OAuth login | (not set) |
101+
| JWT_SECRET | JWT signing secret | `test` |
102+
| JWT_EXPIRATION_TIME | JWT access token expiration time | `1h` |
103+
| JWT_REFRESH_EXPIRATION_TIME | JWT refresh token expiration time | `7d` |
104+
| COLLAB_TOKEN_EXPIRY | Collaboration token expiration time | `1h` |
105+
106+
::: info
107+
The time format is compatible with [Vercel MS](https://github.com/vercel/ms).
108+
:::
109+
110+
#### Email Authentication
111+
112+
| Env | Description | Default Value |
113+
| --- | --- | --- |
114+
| EMAIL_AUTH_ENABLED | Whether to enable email authentication | `true` |
115+
| EMAIL_SENDER | Email sender | `Refly <[email protected]>` |
116+
| RESEND_API_KEY | [Resend](https://resend.com/) API key, used for sending emails | `re_123` |
117+
118+
::: warning
119+
The default `RESEND_API_KEY` is invalid (just a placeholder). Please set your own API key if needed.
120+
:::
121+
122+
#### GitHub Authentication
123+
124+
| Env | Description | Default Value |
125+
| --- | --- | --- |
126+
| GITHUB_AUTH_ENABLED | Whether to enable GitHub authentication | `false` |
127+
| GITHUB_CLIENT_ID | GitHub OAuth client ID | `test` |
128+
| GITHUB_CLIENT_SECRET | GitHub OAuth client secret | `test` |
129+
| GITHUB_CALLBACK_URL | GitHub OAuth callback URL | `test` |
130+
131+
::: warning
132+
The default OAuth credentials are invalid (just a placeholder). Please set your own GitHub OAuth credentials if needed.
133+
:::
134+
135+
::: info
136+
You can learn more about GitHub OAuth at [GitHub Developer](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).
137+
:::
138+
139+
#### Google Authentication
140+
141+
| Env | Description | Default Value |
142+
| --- | --- | --- |
143+
| GOOGLE_AUTH_ENABLED | Whether to enable Google authentication | `false` |
144+
| GOOGLE_CLIENT_ID | Google OAuth client ID | `test` |
145+
| GOOGLE_CLIENT_SECRET | Google OAuth client secret | `test` |
146+
| GOOGLE_CALLBACK_URL | Google OAuth callback URL | `test` |
147+
148+
::: warning
149+
The default OAuth credentials are invalid (just a placeholder). Please set your own Google OAuth credentials if needed.
150+
:::
151+
152+
::: info
153+
You can learn more about Google OAuth at [Google Developer](https://developers.google.com/identity/protocols/oauth2).
154+
:::
155+
156+
### Embeddings Configuration
157+
158+
| Env | Description | Default Value |
159+
| --- | --- | --- |
160+
| EMBEDDINGS_PROVIDER | Embeddings provider (either `jina`, `fireworks` or `openai`) | `jina` |
161+
| EMBEDDINGS_MODEL_NAME | Embeddings model name | `jina-embeddings-v3` |
162+
| EMBEDDINGS_DIMENSIONS | Embedding vector dimensions | `768` |
163+
| EMBEDDINGS_BATCH_SIZE | Batch size for embedding processing | `512` |
164+
165+
::: warning
166+
The default `EMBEDDINGS_PROVIDER` is `jina`. If you want to use other embeddings providers, please set the corresponding environment variables.
167+
:::
168+
169+
::: warning
170+
`EMBEDDINGS_DIMENSIONS` must be set to the same value as `REFLY_VEC_DIM` in Qdrant.
171+
:::
172+
173+
### Reranker
174+
175+
| Env | Description | Default Value |
176+
| --- | --- | --- |
177+
| RERANKER_TOP_N | Number of top results to rerank | `10` |
178+
| RERANKER_MODEL | Reranker model name | `jina-reranker-v2-base-multilingual` |
179+
| RERANKER_RELEVANCE_THRESHOLD | Relevance threshold for reranking | `0.5` |
180+
181+
::: warning
182+
Currently, only Jina rerankers are supported. You need to set the `JINA_API_KEY` environment variable.
183+
:::
184+
185+
### Skill Execution
186+
187+
| Env | Description | Default Value |
188+
| --- | --- | --- |
189+
| REFLY_DEFAULT_MODEL | Default AI model | `openai/gpt-4o-mini` |
190+
| SKILL_IDLE_TIMEOUT | Skill idle timeout in milliseconds | `60000` |
191+
| SKILL_EXECUTION_TIMEOUT | Skill execution timeout in milliseconds | `180000` |
192+
193+
### Stripe
194+
195+
| Env | Description | Default Value |
196+
| --- | --- | --- |
197+
| STRIPE_API_KEY | Stripe API key | (not set) |
198+
| STRIPE_ACCOUNT_WEBHOOK_SECRET | Stripe account webhook secret | `test` |
199+
| STRIPE_ACCOUNT_TEST_WEBHOOK_SECRET | Stripe test account webhook secret | `test` |
200+
| STRIPE_SESSION_SUCCESS_URL | Stripe success redirect URL | (not set) |
201+
| STRIPE_SESSION_CANCEL_URL | Stripe cancellation redirect URL | (not set) |
202+
| STRIPE_PORTAL_RETURN_URL | Stripe customer portal return URL | (not set) |
203+
204+
### Quota
205+
206+
#### Request Quota
207+
208+
| Env | Description | Default Value |
209+
| --- | --- | --- |
210+
| QUOTA_T1_REQUEST | Tier 1 request quota | `-1` |
211+
| QUOTA_T2_REQUEST | Tier 2 request quota | `-1` |
212+
213+
#### Storage Quota
214+
215+
| Env | Description | Default Value |
216+
| --- | --- | --- |
217+
| QUOTA_STORAGE_FILE | File storage quota | `-1` |
218+
| QUOTA_STORAGE_OBJECT | Object storage quota | `-1` |
219+
| QUOTA_STORAGE_VECTOR | Vector storage quota | `-1` |
220+
221+
## Web Frontend
222+
223+
The following are the detailed configurations for the web frontend. You can inject these environment variables into the `refly_web` container.
224+
225+
### General Config
226+
227+
| Env | Description | Default Value |
228+
| --- | --- | --- |
229+
| REFLY_API_URL | Refly API server URL | `http://localhost:5800` |
230+
| COLLAB_URL | Collaboration endpoint URL | `http://localhost:5801` |

Diff for: ‎guide/self-deploy.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Self Deploy
2+
3+
## Prerequisites {#prerequisites}
4+
5+
To self-deploy Refly, you need to have the following installed:
6+
7+
- Docker
8+
- Docker Compose
9+
- Optional: PostgreSQL client (either `psql` or GUI-based tools), used for managing usable LLM models
10+
11+
::: info
12+
We plan to provide a fully-functional native application in the future, offering seamless installation experience in a privacy-focused manner. Stay tuned!
13+
:::
14+
15+
## Steps {#steps}
16+
17+
1. Clone the repository
18+
19+
```bash
20+
git clone https://github.com/refly-ai/refly.git
21+
```
22+
23+
::: tip
24+
If you only need to deploy with Docker, you can add `--depth 1` to the `clone` command to save disk space and download time.
25+
:::
26+
27+
2. Prepare the environment
28+
29+
```bash
30+
cd refly/deploy/docker
31+
cp .env.example .env
32+
```
33+
34+
Notes on environment variables:
35+
36+
- **Envs for LLM inference**:
37+
- `OPENAI_API_KEY`: Your OpenAI API key
38+
- `OPENROUTER_API_KEY`: Your OpenRouter API key (This will override offical OpenAI endpoint if provided)
39+
- **Envs for Embeddings**:
40+
- `EMBEDDINGS_PROVIDER`: Embeddings provider, currently support `openai`, `jina` and `fireworks`
41+
- `EMBEDDINGS_MODEL_NAME`: The name of the embeddings model, which could be different for different providers
42+
- `OPENAI_API_KEY`: Required if `EMBEDDINGS_PROVIDER` is `openai`
43+
- `JINA_API_KEY`: Required if `EMBEDDINGS_PROVIDER` is `jina`
44+
- `FIREWORKS_API_KEY`: Required if `EMBEDDINGS_PROVIDER` is `fireworks`
45+
- **Envs for Web Search**:
46+
- `SERPER_API_KEY`: Serper API key
47+
48+
::: tip
49+
A comprehensive list of all the configuration options is available in the [Configuration](./configuration.md).
50+
:::
51+
52+
::: warning
53+
Currently, the application will be provisioned with OpenRouter-compatible model names, as you can see. If `OPENROUTER_API_KEY` is not provided, the application will use the official OpenAI endpoint, and you need to make adjustments to the model configuration:
54+
55+
```sql
56+
UPDATE refly.model_info SET name = TRIM(LEADING 'openai/' FROM name) WHERE provider = 'openai';
57+
```
58+
:::
59+
60+
3. Start the docker compose file
61+
62+
```bash
63+
docker compose up -d
64+
```
65+
66+
You can run `docker ps` to check the status of the containers. The expected status for each container should be `Up` and `healthy`. An example output is shown below:
67+
68+
```bash
69+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
70+
71681217973e reflyai/refly-api:latest "docker-entrypoint.s…" 5 hours ago Up 5 hours (healthy) 3000/tcp, 0.0.0.0:5800-5801->5800-5801/tcp, :::5800-5801->5800-5801/tcp refly_api
71+
462d7e1181ca reflyai/qdrant:v1.13.1 "./entrypoint.sh" 5 hours ago Up 5 hours (healthy) 0.0.0.0:6333-6334->6333-6334/tcp, :::6333-6334->6333-6334/tcp refly_qdrant
72+
fd287fa0a04e redis/redis-stack:6.2.6-v18 "/entrypoint.sh" 5 hours ago Up 5 hours (healthy) 0.0.0.0:6379->6379/tcp, :::6379->6379/tcp, 0.0.0.0:8001->8001/tcp, :::8001->8001/tcp refly_redis
73+
16321d38fc34 reflyai/refly-web:latest "/docker-entrypoint.…" 5 hours ago Up 5 hours 0.0.0.0:5700->80/tcp, [::]:5700->80/tcp refly_web
74+
2e14ec2e55a2 reflyai/elasticsearch:7.10.2 "/tini -- /usr/local…" 5 hours ago Up 5 hours (healthy) 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp, 9300/tcp refly_elasticsearch
75+
a13f349fe35b minio/minio:RELEASE.2025-01-20T14-49-07Z "/usr/bin/docker-ent…" 5 hours ago Up 5 hours (healthy) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp refly_minio
76+
e7b398dbd02b postgres:16-alpine "docker-entrypoint.s…" 5 hours ago Up 5 hours (healthy) 0.0.0.0:5432->5432/tcp, :::5432->5432/tcp refly_db
77+
```
78+
79+
Finally, you can access the Refly application in `http://localhost:5700`.
80+
81+
## Troubleshooting {#troubleshooting}
82+
83+
If the application fails to function properly, you can try the following steps:
84+
85+
1. Run `docker ps` to identify unhealthy containers.
86+
2. Run `docker logs <container_id>` to get more information about the error.
87+
3. If the unhealthy container is `refly_api`, you can run `docker restart refly_api` to restart the container.
88+
4. For others, you can search for the cause of error messages in the container's logs.
89+
90+
If the issue persists, you can raise an issue in our [GitHub repository](https://github.com/refly-ai/refly/issues), or contact us in our [Discord Server](https://discord.gg/bWjffrb89h).

0 commit comments

Comments
 (0)