Skip to content
This repository was archived by the owner on Dec 10, 2025. It is now read-only.

Commit d7ae246

Browse files
alphatownsmanalphatownsman
committed
initial import
0 parents  commit d7ae246

23 files changed

+1597
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
this is documentation for [NeoDB official site](https://neodb.net), see [neodb](../neodb) for server source code.
2+

‎docs/api.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# API
2+
3+
## Endpoints
4+
5+
NeoDB has a set of API endpoints mapping to its functions like marking a book or listing collections, they can be found in swagger based API documentation at `/developer/` of your running instance, [a version of it](https://neodb.social/developer/) is available on our flagship instance.
6+
7+
NeoDB also supports a subset of Mastodon API, details can be found in [Mastodon API documentation](https://docs.joinmastodon.org/api/).
8+
9+
Both set of APIs can be accessed by the same access token.
10+
11+
## How to authorize
12+
13+
### Create an application
14+
15+
you must have at least one URL included in the Redirect URIs field, e.g. `https://example.org/callback`, or use `urn:ietf:wg:oauth:2.0:oob` if you don't have a callback URL.
16+
17+
```
18+
curl https://neodb.social/api/v1/apps \
19+
-d client_name=MyApp \
20+
-d redirect_uris=https://example.org/callback \
21+
-d website=https://my.site
22+
```
23+
24+
and save of the `client_id` and `client_secret` returned in the response:
25+
26+
```
27+
{
28+
"client_id": "CLIENT_ID",
29+
"client_secret": "CLIENT_SECRET",
30+
"name": "MyApp",
31+
"redirect_uri": "https://example.org/callback",
32+
"vapid_key": "PUSH_KEY",
33+
"website": "https://my.site"
34+
}
35+
```
36+
37+
38+
### Guide your user to open this URL
39+
40+
```
41+
https://neodb.social/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://example.org/callback&scope=read+write
42+
```
43+
44+
### Once authorizated by user, it will redirect to `https://example.org/callback` with a `code` parameter:
45+
46+
```
47+
https://example.org/callback?code=AUTH_CODE
48+
```
49+
50+
### Obtain access token with the following POST request:
51+
52+
```
53+
curl https://neodb.social/oauth/token \
54+
-d "client_id=CLIENT_ID" \
55+
-d "client_secret=CLIENT_SECRET" \
56+
-d "code=AUTH_CODE" \
57+
-d "redirect_uri=https://example.org/callback" \
58+
-d "grant_type=authorization_code"
59+
```
60+
61+
and access token will be returned in the response:
62+
63+
```
64+
{
65+
"access_token": "ACCESS_TOKEN",
66+
"token_type": "Bearer",
67+
"scope": "read write"
68+
}
69+
```
70+
71+
### Use the access token to access protected endpoints like `/api/me`
72+
73+
```
74+
curl -H "Authorization: Bearer ACCESS_TOKEN" -X GET https://neodb.social/api/me
75+
```
76+
77+
and response will be returned accordingly:
78+
79+
```
80+
{"url": "https://neodb.social/users/xxx/", "external_acct": "xxx@yyy.zzz", "display_name": "XYZ", "avatar": "https://yyy.zzz/xxx.gif"}
81+
```

‎docs/apps.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Apps
2+
3+
NeoDB web version will provide the most features and experience, while some third-party apps are also available below.
4+
5+
## Apps for NeoDB
6+
7+
A few apps for NeoDB are being actively developed:
8+
9+
- [Piecelet](https://piecelet.app) by `@piecelet@mastodon.social` - [App Store](https://apps.apple.com/app/piecelet-for-neodb/id6739444863) / [Source Code](https://github.com/lcandy2/neodb-app)
10+
- [Chihu](https://chihu.app) by `@chihu@mastodon.social` - [Test Flight](https://testflight.apple.com/join/WmbnP9Vx)
11+
12+
These apps are not affiliated with NeoDB, but they are being developed with the support of this community. If you are also developing an app for NeoDB, and wish to share that with the community, please [edit this file](https://github.com/neodb-social/neodb/edit/main/docs/apps.md) and submit a pull request.
13+
14+
15+
## Mastodon apps
16+
17+
[Mastodon compatible mobile and native apps](https://joinmastodon.org/apps) can be used to log in and utilize the micro-blogging features in NeoDB server.
18+
19+
In addition to micro-blogging, Mastodon compatible can also be used to take note on book you are currently reading. Just head to bookmark section in your app, your currently reading books are listed there as bookmarked posts, replying any of them will make a note for that book.

‎docs/assets/logo.svg‎

Lines changed: 140 additions & 0 deletions
Loading

‎docs/configuration.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Configuration
2+
3+
4+
## Important settings you may want to change first
5+
6+
absolutely set these in `.env` before start the instance for the first time:
7+
8+
- `NEODB_SECRET_KEY` - 50 characters of random string, no white space
9+
- `NEODB_SITE_NAME` - the name of your site
10+
- `NEODB_SITE_DOMAIN` - the domain name of your site
11+
12+
**`NEODB_SECRET_KEY` and `NEODB_SITE_DOMAIN` must not be changed later.**
13+
14+
if you are doing debug or development:
15+
16+
- `NEODB_DEBUG` - True will turn on debug for both neodb and takahe, turn off relay, and reveal self as debug mode in nodeinfo (so peers won't try to run fedi search on this node)
17+
- `NEODB_IMAGE` - the docker image to use, `neodb/neodb:edge` for the main branch
18+
19+
## Settings for customization
20+
21+
- `NEODB_SITE_LOGO`
22+
- `NEODB_SITE_ICON`
23+
- `NEODB_USER_ICON`
24+
- `NEODB_SITE_COLOR` - one of [these color schemes](https://picocss.com/docs/colors)
25+
- `NEODB_SITE_INTRO`
26+
- `NEODB_SITE_HEAD`
27+
- `NEODB_SITE_DESCRIPTION`
28+
- `NEODB_PREFERRED_LANGUAGES` - preferred languages when importing titles from 3rd party sites like TMDB and Steam, comma-separated list of ISO-639-1 two-letter codes, `en,zh` by default. It can includes languages with no UI translations yet, e.g. if set to `ja,en,zh`, NeoDB scraper will fetch catalog metadata in three languages if they are available from third party sites, Japanese users (= whose browser language set to ja-JP) will see English UI with Japanese metadata.
29+
- `NEODB_DISCOVER_FILTER_LANGUAGE` - `False` by default; when set to `True`, `/discover/` will only show items with languages match one of `NEODB_PREFERRED_LANGUAGES`.
30+
- `NEODB_DISCOVER_SHOW_LOCAL_ONLY` - `False` by default; when set to `True`, only show items marked by local users rather than entire network on `/discover/`
31+
- `NEODB_DISCOVER_UPDATE_INTERVAL` - minutes between each update for popular items on `/discover/`
32+
- `NEODB_SITE_LINKS` - a list of title and links to show in the footer, comma separated, e.g. `Feedback=https://discord.gg/8KweCuApaK,ToS=/pages/rules/`
33+
- `NEODB_INVITE_ONLY` - `False` by default, set to `True` to require invite code(generated by `neodb-manage invite --create`) to register
34+
- `NEODB_ENABLE_LOCAL_ONLY` - `False` by default, set to `True` to allow user to post marks as "local public"
35+
- `NEODB_LOGIN_MASTODON_WHITELIST` - a list of Mastodon instances to allow login from, comma separated
36+
- `NEODB_EMAIL_FROM` - the email address to send email from
37+
- `NEODB_EMAIL_URL` - email sender configuration, e.g.
38+
- `smtp://<username>:<password>@<host>:<port>`
39+
- `smtp+tls://<username>:<password>@<host>:<port>`
40+
- `smtp+ssl://<username>:<password>@<host>:<port>`
41+
- `anymail://<anymail_backend_name>?<anymail_args>`, to send email via email service providers, see [anymail doc](https://anymail.dev/)
42+
43+
## Settings for administration
44+
- `DISCORD_WEBHOOKS` - Discord channel to send notification about user submitted suggestion and changes, e.g. `suggest=https://discord.com/api/webhooks/123/abc,audit=https://discord.com/api/webhooks/123/def`. Both suggest and audit channels must be in forum mode.
45+
- `NEODB_SENTRY_DSN` , `TAKAHE_SENTRY_DSN` - [Sentry](https://sentry.io/) DSN to log errors.
46+
47+
## Settings for Federation
48+
49+
- `NEODB_SEARCH_PEERS` is empty by default, which means NeoDB will search all known peers running production version of NeoDB when user look for items. This can be set to a comma-separated list of host names, so that NeoDB will only search those servers; or search no other peers if set to just `-`.
50+
51+
- `NEODB_DISABLE_DEFAULT_RELAY` is set to `False` by default, the server will send and receive public posts from `relay.neodb.net`.
52+
53+
`relay.neodb.net` is [open sourced](https://github.com/neodb-social/neodb-relay) and operated by NeoDB developers, it works like most ActivityPub relays except it only relays between NeoDB instances, it helps public information like catalogs and trends flow between NeoDB instances. You may set it to `True` if you don't want to relay public posts with other NeoDB instances.
54+
55+
56+
## Settings for external item sources
57+
58+
- `SPOTIFY_API_KEY` - base64('CLIENT_ID:SECRET'), see [spotify doc](https://developer.spotify.com/documentation/web-api/tutorials/client-credentials-flow)
59+
- `TMDB_API_V3_KEY` - API v3 key from [TMDB](https://developer.themoviedb.org/)
60+
- `GOOGLE_API_KEY` - API key for [Google Books](https://developers.google.com/books/docs/v1/using)
61+
- `DISCOGS_API_KEY` - personal access token from [Discogs](https://www.discogs.com/settings/developers)
62+
- `IGDB_API_CLIENT_ID`, `IGDB_API_CLIENT_SECRET` - IGDB [keys](https://api-docs.igdb.com/)
63+
- `NEODB_SEARCH_SITES` is empty by default, which means NeoDB will search all available sources. This can be set to a comma-separated list of site names (e.g. `goodreads,googlebooks,spotify,tmdb,igdb,bandcamp,apple_podcast`), so that NeoDB will only search those sites; or not search any of them if set to just `-`.
64+
65+
66+
## Other maintenance tasks
67+
68+
Add alias to your shell for easier access
69+
70+
```
71+
alias neodb-manage='docker-compose --profile production run --rm shell neodb-manage'
72+
```
73+
74+
Toggle user's active, staff and super user status
75+
76+
```
77+
neodb-manage user --active <username>
78+
neodb-manage user --staff <username>
79+
neodb-manage user --super <username>
80+
```
81+
82+
create a super user; delete a user / remote identity (`takahe-stator` and `neodb-worker` containers must be running to complete the deletion)
83+
```
84+
neodb-manage createsuperuser
85+
neodb-manage user --delete username
86+
neodb-manage user --delete username@remote.instance
87+
```
88+
89+
Create an invite link
90+
91+
```
92+
neodb-manage invite --create
93+
```
94+
95+
Manage user tasks and cron jobs
96+
97+
```
98+
neodb-manage task --list
99+
neodb-manage cron --list
100+
```
101+
102+
Manage search index
103+
```
104+
neo-manage index --reindex
105+
```
106+
107+
Crawl links
108+
```
109+
neodb-manage cat [--save] <url> # parse / save a supported link
110+
neodb-manage crawl <url> # crawl all recognizable links from a page
111+
```
112+
113+
114+
## Run PostgresQL/Redis/Typesense without Docker
115+
116+
It's currently possible but quite cumbersome to run without Docker, hence not recommended. However it's possible to only use docker to run neodb server but reuse existing PostgresQL/Redis/Typesense servers with `compose.override.yml`, an example for reference:
117+
118+
```
119+
services:
120+
redis:
121+
profiles: ['disabled']
122+
typesense:
123+
profiles: ['disabled']
124+
neodb-db:
125+
profiles: ['disabled']
126+
takahe-db:
127+
profiles: ['disabled']
128+
migration:
129+
extra_hosts:
130+
- "host.docker.internal:host-gateway"
131+
depends_on: !reset []
132+
neodb-web:
133+
extra_hosts:
134+
- "host.docker.internal:host-gateway"
135+
depends_on: !reset []
136+
healthcheck: !reset {}
137+
neodb-web-api:
138+
extra_hosts:
139+
- "host.docker.internal:host-gateway"
140+
depends_on: !reset []
141+
healthcheck: !reset {}
142+
neodb-worker:
143+
extra_hosts:
144+
- "host.docker.internal:host-gateway"
145+
depends_on: !reset []
146+
neodb-worker-extra:
147+
extra_hosts:
148+
- "host.docker.internal:host-gateway"
149+
depends_on: !reset []
150+
takahe-web:
151+
extra_hosts:
152+
- "host.docker.internal:host-gateway"
153+
depends_on: !reset []
154+
takahe-stator:
155+
extra_hosts:
156+
- "host.docker.internal:host-gateway"
157+
depends_on: !reset []
158+
shell:
159+
extra_hosts:
160+
- "host.docker.internal:host-gateway"
161+
depends_on: !reset []
162+
root:
163+
extra_hosts:
164+
- "host.docker.internal:host-gateway"
165+
depends_on: !reset []
166+
dev-neodb-web:
167+
extra_hosts:
168+
- "host.docker.internal:host-gateway"
169+
depends_on: !reset []
170+
dev-neodb-worker:
171+
extra_hosts:
172+
- "host.docker.internal:host-gateway"
173+
depends_on: !reset []
174+
dev-takahe-web:
175+
extra_hosts:
176+
- "host.docker.internal:host-gateway"
177+
depends_on: !reset []
178+
dev-takahe-stator:
179+
extra_hosts:
180+
- "host.docker.internal:host-gateway"
181+
depends_on: !reset []
182+
dev-shell:
183+
extra_hosts:
184+
- "host.docker.internal:host-gateway"
185+
depends_on: !reset []
186+
dev-root:
187+
extra_hosts:
188+
- "host.docker.internal:host-gateway"
189+
depends_on: !reset []
190+
```
191+
(`extra_hosts` is only needed if PostgresQL/Redis/Typesense is on your host server)
192+
193+
194+
## Multiple instances on one server
195+
196+
It's possible to run multiple clusters in one host server with docker compose, as long as `NEODB_SITE_DOMAIN`, `NEODB_PORT` and `NEODB_DATA` are different.
197+
198+
199+
## Scaling up
200+
201+
For high-traffic instance, spin up these configurations to a higher number, as long as the host server can handle them:
202+
203+
- `NEODB_WEB_WORKER_NUM`
204+
- `NEODB_API_WORKER_NUM`
205+
- `NEODB_RQ_WORKER_NUM`
206+
- `TAKAHE_WEB_WORKER_NUM`
207+
- `TAKAHE_STATOR_CONCURRENCY`
208+
- `TAKAHE_STATOR_CONCURRENCY_PER_MODEL`
209+
210+
Further scaling up with multiple nodes (e.g. via Kubernetes) is beyond the scope of this document, but consider run db/redis/typesense separately, and then duplicate web/worker/stator containers as long as connections and mounts are properly configured; `migration` only runs once when start or upgrade, it should be kept that way.

0 commit comments

Comments
 (0)