swadhin / justapi public

p1b: enhance Installation page — verify command, Docker, platform notes, troubleshooting

swadhinbiswas committed 3 months ago
72782cc
1 parent 92dbd8c
commit 72782cc
1 file changed
+105 -5
Showing 1 changed file+105-5
docs_site/src/content/docs/getting-started/installation.md
▼docs_site/src/content/docs/getting-started/installation.md
+105-5
@@ -5,8 +5,8 @@ description: How to install JustAPI via pip, cargo, or building from source.
5
5
6
6
## Prerequisites
7
7
8
-* **Python:** 3.11, 3.12, 3.13, or 3.14 (including 3.13t/3.14t free-threaded builds)
9
-* **Rust:** 1.85+ (only required if building from source)
8
+- **Python:** 3.11, 3.12, 3.13, or 3.14 (including 3.13t/3.14t free-threaded builds)
9
+- **Rust:** 1.85+ (only required if building from source)
10
10
11
11
## Install via pip
12
12
@@ -16,26 +16,126 @@ Install the official pre-compiled wheel package from PyPI:
16
16
pip install justapi
17
17
```
18
18
19
-To install optional features (such as Pydantic v2 and Jinja2 support):
19
+To install optional features (Pydantic v2, Jinja2, XML support):
20
20
21
21
```bash
22
22
pip install "justapi[full]"
23
23
```
24
24
25
+### Verify Installation
26
+
27
+```bash
28
+python -c "import justapi; print(justapi.__version__)"
29
+# Output: 2.0.0
30
+```
31
+
25
32
## Install CLI Tooling (`justapi-cli`)
26
33
27
-Install the native Rust project generator and dev server CLI via Cargo:
34
+The `justapi` CLI includes the project scaffolder, dev server with hot-reload, and database migration runner.
28
35
29
36
```bash
37
+# Install from source (requires Rust 1.85+)
30
38
cargo install justapi-cli
39
+
40
+# Verify
41
+justapi --version
42
+# Output: justapi 2.0.0
31
43
```
32
44
45
+## Docker
46
+
47
+Pull the official Docker image:
48
+
49
+```bash
50
+docker pull ghcr.io/justapi/justapi:latest
51
+```
52
+
53
+Or use the multi-stage `Dockerfile` in the repository root for custom builds.
54
+
33
55
## Build from Source
34
56
35
-To compile the native PyO3 bindings locally with `maturin`:
57
+Clone the repository and build the native PyO3 bindings with `maturin`:
36
58
37
59
```bash
38
60
git clone https://github.com/swadhinbiswas/JustAPI.git
39
61
cd JustAPI
62
+
63
+# Create a virtual environment
64
+python -m venv .venv
65
+source .venv/bin/activate
66
+
67
+# Build the Rust extension
40
68
maturin develop --release --manifest-path crates/justapi-py/Cargo.toml
69
+
70
+# Install Python dependencies
71
+pip install pydantic
72
+
73
+# Build the CLI (optional)
74
+cargo install --path crates/justapi-cli
75
+```
76
+
77
+### Build with Feature Flags
78
+
79
+```bash
80
+# Enable TLS, compression, and OpenTelemetry support
81
+maturin develop --release -m crates/justapi-py/Cargo.toml --features tls,compression,opentelemetry
41
82
```
83
+
84
+## Platform-Specific Notes
85
+
86
+### Linux
87
+
88
+Pre-built wheels are available for `manylinux_2_28` (x86_64 and ARM64) and `musllinux_1_2` (Alpine).
89
+
90
+Required system packages:
91
+
92
+```bash
93
+# Debian/Ubuntu
94
+apt-get install libssl-dev pkg-config python3-dev
95
+
96
+# Alpine
97
+apk add openssl-dev pkgconfig python3-dev rust cargo
98
+```
99
+
100
+### macOS
101
+
102
+Pre-built wheels available for x86_64 and ARM64 (Apple Silicon).
103
+
104
+```bash
105
+# Ensure you have Xcode Command Line Tools
106
+xcode-select --install
107
+```
108
+
109
+### Windows
110
+
111
+Pre-built wheels available for x64. When building from source, install Visual Studio Build Tools with C++ support.
112
+
113
+## Troubleshooting
114
+
115
+### `pip install` fails with build error
116
+
117
+Ensure you have Rust installed. If you don't need to build from source, try the pre-built wheel:
118
+
119
+```bash
120
+pip install --only-binary=justapi justapi
121
+```
122
+
123
+### `maturin develop` fails
124
+
125
+```bash
126
+# Ensure you're in a virtual environment
127
+python -m venv .venv
128
+source .venv/bin/activate
129
+
130
+# Update pip and maturin
131
+pip install --upgrade pip maturin
132
+```
133
+
134
+### ImportError: No module named `_justapi`
135
+
136
+The Rust extension wasn't built. Run `maturin develop --release` from the repository root.
137
+
138
+## Next Steps
139
+
140
+- [First Steps](/getting-started/first-steps/) — Build your first API endpoint in 2 minutes
141
+- [CLI Project Scaffolder](/getting-started/cli-scaffolder/) — Generate complete project templates
42
142