Skip to content

Commit f4ef381

Browse files
PttCodingManPttCodingMan
committed
feat: add readme
1 parent b1e2d78 commit f4ef381

5 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎.github/workflows/build-and-push.yml‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
name: Build and Push Docker Images
2+
3+
on:
4+
push:
5+
branches: [main]
6+
tags: ['v*']
7+
pull_request:
8+
branches: [main]
9+
10+
env:
11+
REGISTRY: ghcr.io
12+
IMAGE_PREFIX: ghcr.io/${{ github.repository }}
13+
14+
jobs:
15+
build-backend:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: read
19+
packages: write
20+
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Set up Docker Buildx
26+
uses: docker/setup-buildx-action@v3
27+
28+
- name: Log in to GitHub Container Registry
29+
if: github.event_name != 'pull_request'
30+
uses: docker/login-action@v3
31+
with:
32+
registry: ${{ env.REGISTRY }}
33+
username: ${{ github.actor }}
34+
password: ${{ secrets.GITHUB_TOKEN }}
35+
36+
- name: Extract metadata
37+
id: meta
38+
uses: docker/metadata-action@v5
39+
with:
40+
images: ${{ env.IMAGE_PREFIX }}/backend
41+
tags: |
42+
type=ref,event=branch
43+
type=semver,pattern={{version}}
44+
type=semver,pattern={{major}}.{{minor}}
45+
type=sha,prefix=
46+
47+
- name: Build and push backend
48+
uses: docker/build-push-action@v6
49+
with:
50+
context: ./backend
51+
push: ${{ github.event_name != 'pull_request' }}
52+
tags: ${{ steps.meta.outputs.tags }}
53+
labels: ${{ steps.meta.outputs.labels }}
54+
cache-from: type=gha
55+
cache-to: type=gha,mode=max
56+
57+
build-frontend:
58+
runs-on: ubuntu-latest
59+
permissions:
60+
contents: read
61+
packages: write
62+
63+
steps:
64+
- name: Checkout
65+
uses: actions/checkout@v4
66+
67+
- name: Set up Docker Buildx
68+
uses: docker/setup-buildx-action@v3
69+
70+
- name: Log in to GitHub Container Registry
71+
if: github.event_name != 'pull_request'
72+
uses: docker/login-action@v3
73+
with:
74+
registry: ${{ env.REGISTRY }}
75+
username: ${{ github.actor }}
76+
password: ${{ secrets.GITHUB_TOKEN }}
77+
78+
- name: Extract metadata
79+
id: meta
80+
uses: docker/metadata-action@v5
81+
with:
82+
images: ${{ env.IMAGE_PREFIX }}/frontend
83+
tags: |
84+
type=ref,event=branch
85+
type=semver,pattern={{version}}
86+
type=semver,pattern={{major}}.{{minor}}
87+
type=sha,prefix=
88+
89+
- name: Build and push frontend
90+
uses: docker/build-push-action@v6
91+
with:
92+
context: ./frontend
93+
push: ${{ github.event_name != 'pull_request' }}
94+
tags: ${{ steps.meta.outputs.tags }}
95+
labels: ${{ steps.meta.outputs.labels }}
96+
cache-from: type=gha
97+
cache-to: type=gha,mode=max

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 JustWiki
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
<p align="center">
2+
<img src="docs/images/logo.png" alt="JustWiki Logo" width="480">
3+
</p>
4+
5+
# JustWiki
6+
7+
A lightweight, self-hosted wiki for small teams. Just clone, run, and write.
8+
9+
## Features
10+
11+
- **Markdown first** — Milkdown WYSIWYG editor with slash commands, Mermaid diagrams, KaTeX math, callout blocks
12+
- **One SQLite file** — no external database needed. Backup = copy one file
13+
- **Full-text search** — FTS5 powered, with optional AI Q&A (Gemini)
14+
- **Version history** — page revisions with diff view
15+
- **Draw.io integration** — embedded diagram editor
16+
- **Themes** — multiple built-in themes
17+
- **PWA ready** — installable on mobile and desktop
18+
- **Docker support** — `docker-compose up` and done
19+
20+
## Tech Stack
21+
22+
| Layer | Stack |
23+
| -------- | ---------------------------------------------- |
24+
| Backend | Python, FastAPI, aiosqlite, Pydantic |
25+
| Frontend | React 19, Vite, Tailwind CSS 4, Zustand |
26+
| Editor | Milkdown (ProseMirror) |
27+
| Database | SQLite (single file) |
28+
| Deploy | Docker Compose |
29+
30+
## Quick Start
31+
32+
### Docker (recommended)
33+
34+
```bash
35+
cp .env.example .env
36+
# edit .env — at minimum change SECRET_KEY and ADMIN_PASS
37+
docker-compose up -d
38+
```
39+
40+
Open http://localhost:3000
41+
42+
### Local Development
43+
44+
```bash
45+
make setup # install backend & frontend dependencies, create .env
46+
make dev # start backend (port 8000) + frontend (port 3000)
47+
```
48+
49+
Requires: Python 3.11+, Node.js 20+, [uv](https://docs.astral.sh/uv/)
50+
51+
## Configuration
52+
53+
All settings live in a single `.env` file. See [.env.example](.env.example) for available options.
54+
55+
Key variables:
56+
57+
| Variable | Description | Default |
58+
| --------------- | ---------------------------------- | -------------------- |
59+
| `SECRET_KEY` | Session signing key | `change-me-...` |
60+
| `ADMIN_USER` | Admin username | `admin` |
61+
| `ADMIN_PASS` | Admin password | `admin` |
62+
| `DB_PATH` | SQLite database path | `./data/just-wiki.db`|
63+
| `AI_ENABLED` | Enable Gemini AI Q&A | `false` |
64+
| `GEMINI_API_KEY`| Gemini API key (when AI enabled) | |
65+
66+
## Makefile Commands
67+
68+
```bash
69+
make dev # Start backend + frontend in dev mode
70+
make dev-backend # Start backend only
71+
make dev-frontend # Start frontend only
72+
make build # Build frontend for production
73+
make backup # Backup SQLite database with timestamp
74+
make clean # Remove database, media, and frontend dist
75+
make docker-up # docker-compose up -d
76+
make docker-down # docker-compose down
77+
make setup # First-time setup (install deps, create .env)
78+
```
79+
80+
## Project Structure
81+
82+
```
83+
just-wiki/
84+
├── backend/ # FastAPI REST API
85+
│ └── app/
86+
│ ├── main.py
87+
│ ├── routers/ # pages, search, media, tags, versions, ...
88+
│ └── services/ # markdown, search, AI, webhook, export
89+
├── frontend/ # React SPA (Vite)
90+
│ └── src/
91+
│ ├── components/
92+
│ │ ├── Editor/ # Milkdown editor
93+
│ │ ├── Viewer/ # Markdown renderer
94+
│ │ ├── Search/ # Search + AI Q&A
95+
│ │ └── Layout/ # Sidebar, Navbar
96+
│ ├── pages/
97+
│ ├── hooks/
98+
│ └── store/ # Zustand
99+
├── data/ # Runtime data (SQLite, media)
100+
├── docker-compose.yml
101+
├── Makefile
102+
└── .env.example
103+
```
104+
105+
## License
106+
107+
This project is licensed under the [MIT License](LICENSE).

‎docker-compose.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
services:
22
backend:
3+
image: ghcr.io/pttcodingman/just-wiki/backend:main
34
build: ./backend
45
ports:
56
- "8000:8000"
@@ -9,6 +10,7 @@ services:
910
restart: unless-stopped
1011

1112
frontend:
13+
image: ghcr.io/pttcodingman/just-wiki/frontend:main
1214
build: ./frontend
1315
ports:
1416
- "3000:3000"

‎docs/images/logo.png‎

5.01 MB
Loading

0 commit comments

Comments
 (0)