NEODB_SITE_INTRO and more documentation

boofilsic/settings.py

@@ -24,6 +24,7 @@ env = environ.FileAwareEnv(
     NEODB_SITE_LOGO=(str, "/s/img/logo.svg"),
     NEODB_SITE_ICON=(str, "/s/img/logo.svg"),
     NEODB_USER_ICON=(str, "/s/img/avatar.svg"),
+    NEODB_SITE_INTRO=(str, ""),
     # Links in site footer
     NEODB_SITE_LINKS=(dict, {}),
     # Invite only mode
@@ -145,6 +146,7 @@ SITE_INFO = {
     "site_logo": env("NEODB_SITE_LOGO"),
     "site_icon": env("NEODB_SITE_ICON"),
     "user_icon": env("NEODB_USER_ICON"),
+    "site_intro": env("NEODB_SITE_INTRO"),
     "site_links": [{"title": k, "url": v} for k, v in env("NEODB_SITE_LINKS").items()],
 }
 

common/templates/_sidebar_anonymous.html

@@ -9,6 +9,11 @@
 {% load bleach_tags %}
 <div class="grid__aside">
   <section>
+    {% if site_intro %}
+      <div hx-get="{{ site_intro }}" hx-trigger="load" hx-swap="outerHTML">
+        <i class="fa-solid fa-compact-disc fa-spin loading"></i>
+      </div>
+    {% else %}
       <article>
         <h3>欢迎 🙋🏻‍♀️ 🙋🏻 🙋🏻‍♂️</h3>
         <p>
@@ -27,5 +32,6 @@
           <i class="fa-solid fa-door-open"></i> &nbsp; <a href="{% url 'users:login' %}">点击这里</a>登录。
         </p>
       </article>
+    {% endif %}
   </section>
 </div>

compose.yml

@@ -19,6 +19,7 @@ x-shared:
       NEODB_SECRET_KEY:
       NEODB_SITE_NAME:
       NEODB_SITE_DOMAIN:
+      NEODB_SITE_INTRO:
       NEODB_SITE_LOGO:
       NEODB_SITE_ICON:
       NEODB_USER_ICON:

doc/development.md

@@ -3,7 +3,7 @@ Development
 
 Overview
 --------
-NeoDB is a Django project, and it runs side by side with a modified version of [Takahe](https://github.com/jointakahe/takahe) (a separate Django project, code in `neodb_takahe` as submodule). They communicate mainly thru database and task queue, the diagram in [Docker Installation](install-docker.md) demostrate a typical architecture. Currently the two are loosely coupled, so you may take either one offline without immediate impact on the other, which makes it very easy to conduct maintenance and troubleshooting separately. In the future, they may get combined but it's not decided and will not be decided very soon.
+NeoDB is a Django project, and it runs side by side with a [modified version](https://github.com/neodb-social/neodb-takahe) of [Takahe](https://github.com/jointakahe/takahe) (a separate Django project, code in `neodb_takahe` as submodule). They communicate mainly thru database and task queue, the diagram in [Docker Installation](install-docker.md) demostrate a typical architecture. Currently the two are loosely coupled, so you may take either one offline without immediate impact on the other, which makes it very easy to conduct maintenance and troubleshooting separately. In the future, they may get combined but it's not decided and will not be decided very soon.
 
 Before writing code
 -------------------
@@ -60,11 +60,16 @@ Preserving test database for alias 'default'...
 
 Development in Docker
 ---------------------
-To run local source code with `docker compose`, add `NEODB_DEBUG=True` in `.env`, and use `--profile dev` instead of `--profile production` in commands. The `dev` profile is different from `production`:
+To run local source code with `docker compose`, add `NEODB_DEBUG=True` in `.env` or host environment, and use `--profile dev` instead of `--profile production` in commands, e.g.:
+```
+$ NEODB_DEBUG=True docker compose --profile dev up -d
+```
+
+The `dev` profile is different from `production`:
 
 - code in `NEODB_SRC` (default: .) and `TAKAHE_SRC` (default: ./neodb-takahe) will be mounted and used in the container instead of code in the image
 - `runserver` with autoreload will be used instead of `gunicorn` for both neodb and takahe web server
-- /static/ and /s/ url are not map to pre-generated/collected static file path,  `NEODB_DEBUG=True` will locate static files from source code
+- /static/ and /s/ url are not map to pre-generated/collected static file path,  `NEODB_DEBUG=True` is required locate static files from source code
 - one `rqworker` container will be started, instead of two
 - use `dev-shell` and `dev-root` to invoke shells, instead of `shell` and `root`
 - there's no automatic `migration` container, but it can be triggered manually via `docker compose run dev-shell neodb-init`
@@ -73,7 +78,7 @@ Note:
 - Python virtual environments inside docker image, which are `/neodb-venv` and `/takahe-venv`, will be used by default. They can be changed to different locations with `TAKAHE_VENV` and `NEODB_VENV` if needed, usually in a case of development code using a package not in docker venv.
 - Some packages inside python virtual environments are platform dependent, so mount venv built by macOS host into the Linux container will likely not work.
 - Python servers are launched as `app` user, who has no write access to anywhere except /tmp and media path, that's by design.
-- Database/redis used in the container cluster are not accessible outside, which is by design. Querying them can be done by either apt update/install client packages in `dev-root` or `root` container, or create `compose.override.yml` to uncomment `ports` section.
+- Database/redis used in the container cluster are not accessible from host directly, which is by design. Querying them can be done by either apt update/install client packages in `dev-root` or `root` container, or create `compose.override.yml` to uncomment `ports` section.
 
 To run local unit tests, use `docker compose run dev-shell neodb-manage test`
 

doc/install-docker.md

@@ -43,7 +43,7 @@ $ sudo usermod -aG docker neouser
 ```
 
 ## Get configuration files
- - create a folder for configuration, eg ~/neodb/config
+ - create a folder for configuration, eg ~/mysite/config
  - grab `compose.yml` and `neodb.env.example` from source code
  - rename `neodb.env.example` to `.env`
 
@@ -67,7 +67,13 @@ $ docker compose pull
 $ docker compose --profile production up -d
 ```
 
-In a minute or so, the site should be up at 127.0.0.1:8000 , you may check it with:
+Starting up for the first time might take a few minutes, depending on download speed, use the following commands for status and logs:
+```
+$ docker compose ps
+$ docker compose --profile production logs -f
+```
+
+In a few seconds, the site should be up at 127.0.0.1:8000 , you may check it with:
 ```
 $ curl http://localhost:8000/nodeinfo/2.0/
 ```
@@ -77,6 +83,8 @@ JSON response will be returned if the server is up and running:
 {"version": "2.0", "software": {"name": "neodb", "version": "0.8-dev"}, "protocols": ["activitypub", "neodb"], "services": {"outbound": [], "inbound": []}, "usage": {"users": {"total": 1}, "localPosts": 0}, "openRegistrations": true, "metadata": {}}
 ```
 
+
+
 ## Make the site available publicly
 
 Next step is to expose `127.0.0.1:8000` to external network as `https://yourdomain.tld` . There are many ways to do it, you may use nginx as a reverse proxy with a ssl cert, or configure a CDN provider to handle the SSL. There's no detailed instruction yet but contributions are welcomed.
@@ -96,7 +104,7 @@ $ docker compose stop neodb-web neodb-worker neodb-worker-extra takahe-web takah
 $ docker compose --profile production up -d
 ```
 
-Otherwise restart the entire cluster:
+Otherwise restart the entire cluster (including database/etc, hence slower):
 ```
 $ docker compose down
 $ docker compose --profile production up -d
@@ -104,6 +112,24 @@ $ docker compose --profile production up -d
 
 If there is `compose.override.yml` in the directory, make sure it's compatible with the updated `compose.yml`.
 
+## Folders explained
+a typical neodb folder after starting up should look like:
+```
+mysite
+├── data                # neodb data folder, location can be changed via NEODB_DATA in .env
+│   ├── neodb-db        # neodb database
+│   ├── neodb-media     # uid must be 1000 (app user in docker image), chmod if not so
+│   ├── redis           # neodb/takahe cache
+│   ├── takahe-cache    # uid must be 33 (www-data user in docker image), chmod if not so
+│   ├── takahe-db       # neodb database
+│   ├── takahe-media    # uid must be 1000 (app user in docker image), chmod if not so
+│   ├── typesense       # neodb search index
+│   └── www-root        # neodb web root for robots.txt, logo.png and etc
+└── config
+    ├── compose.yml     # copied from neodb release
+    └── .env            # your configuration, see neodb.env.example
+```
+
 ## Troubleshooting
 
  - `docker compose ps` to see if any service is down, (btw it's normal that `migration` is in `Exit 0` state)

neodb.env.example

@@ -10,6 +10,7 @@ NEODB_SITE_DOMAIN=example.site
 # NEODB_SITE_DOMAIN=${CODESPACE_NAME}-8000.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}
 
 # Change these too
+NEODB_SITE_INTRO=/welcome.html
 NEODB_SITE_LOGO=/logo.png
 NEODB_SITE_ICON=/icon.png
 NEODB_SITE_LINKS=@NiceDB=https://donotban.com/@testie,@NeoDB=https://mastodon.social/@neodb