104 lines
2.5 KiB
Markdown
104 lines
2.5 KiB
Markdown
Bullet-proof recipe: MkDocs on a **remote Linux host**, served from Miniconda, reachable from your browser at `http://YOUR_HOST_IP:8000`.
|
||
|
||
---
|
||
|
||
### 1. SSH into your server & install Miniconda
|
||
```bash
|
||
# download latest installer
|
||
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
|
||
chmod +x Miniconda3-latest-Linux-x86_64.sh
|
||
./Miniconda3-latest-Linux-x86_64.sh # say “yes” to auto-init
|
||
exec $SHELL # reload shell
|
||
```
|
||
|
||
---
|
||
|
||
### 2. Create & activate an isolated environment
|
||
```bash
|
||
conda create -n mkdocs python=3.11 -y
|
||
conda activate mkdocs
|
||
```
|
||
|
||
---
|
||
|
||
### 3. Install MkDocs + Material theme
|
||
```bash
|
||
pip install mkdocs mkdocs-material
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Drop your **configuration.yml** in place
|
||
Assume you already have a file called `configuration.yml` that contains *everything* (MkDocs will accept any name as long as you point to it).
|
||
|
||
Example directory layout (adjust to taste):
|
||
```
|
||
~/notes/
|
||
├── configuration.yml # your ready-made config
|
||
└── docs/
|
||
├── index.md
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
### 5. One-liner to expose the docs publicly
|
||
```bash
|
||
cd ~/notes
|
||
mkdocs serve \
|
||
--config-file configuration.yml \
|
||
--dev-addr 0.0.0.0:8000 \
|
||
--no-livereload # optional: drops websocket, lighter
|
||
```
|
||
|
||
What this does
|
||
- `--dev-addr 0.0.0.0:8000` listens on **all interfaces**, so the service is reachable at `http://HOST_IP:8000` .
|
||
- `--config-file` lets you keep the non-standard name `configuration.yml`.
|
||
|
||
---
|
||
|
||
### 6. Quick sanity check
|
||
From your **local machine**:
|
||
```bash
|
||
curl http://HOST_IP:8000
|
||
```
|
||
You should get the HTML of your landing page.
|
||
|
||
---
|
||
|
||
### 7. (Optional) systemd service so it restarts on reboot
|
||
Create `/etc/systemd/system/mkdocs.service`:
|
||
```ini
|
||
[Unit]
|
||
Description=MkDocs dev server
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=YOUR_USER
|
||
WorkingDirectory=/home/YOUR_USER/notes
|
||
ExecStart=/home/YOUR_USER/miniconda3/envs/mkdocs/bin/mkdocs serve \
|
||
--config-file /home/YOUR_USER/notes/configuration.yml \
|
||
--dev-addr 0.0.0.0:8000 --no-livereload
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
Then:
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now mkdocs
|
||
```
|
||
|
||
---
|
||
|
||
### 8. Firewall / cloud security group
|
||
Open **TCP 8000** inbound (e.g. `sudo ufw allow 8000/tcp` or your cloud panel).
|
||
|
||
---
|
||
|
||
### 9. Browse & iterate
|
||
Visit `http://HOST_IP:8000` from anywhere—every save in `docs/` triggers an auto-reload (unless `--no-livereload` was used).
|
||
|
||
That’s it—drop more Markdown files in `docs/`, edit `configuration.yml`, and you’re live. |