Run MkDocs on iPad with iSH and Browse It Locally 🎉

Mohammed AlShannaq — Sat, 04 Oct 2025 01:49:01 +0000

Have you ever thought about turning your iPad into a mini documentation server?
With iSH (a Linux shell for iOS) and MkDocs, you can not only build documentation projects right on your iPad, but also serve and browse them locally in Chrome or Safari on the same device! 🚀

Why do this?

📝 Write and preview your documentation on the go, without a laptop.
💡 Turn your iPad into a self-contained dev and docs environment.
🌍 Browse your MkDocs site locally as if it’s hosted online — but it’s all happening inside your iPad.

Step 1: Install iSH

Grab iSH Shell from the App Store. It runs Alpine Linux inside iOS — lightweight and perfect for experiments like this.

Step 2: Install Python & Build Tools

Inside iSH, update and install the required packages:

apk update
apk add python3 py3-pip build-base python3-dev libffi-dev openssl-dev
pip install --upgrade pip setuptools wheel

Step 3: Install MkDocs

pip install mkdocs mkdocs-material

Check if it works:

mkdocs —version

Step 4: Create a Project

mkdocs new mydocs
cd mydocs

Step 5: Serve the Site

Here’s the magic part — run the built-in dev server on 127.0.0.1:

mkdocs serve -a 127.0.0.1:8000

Step 6: Browse on Your iPad 🎉

Now open Chrome or Safari on your iPad and go to:

http://127.0.0.1:8000/

Boom! You’re browsing your MkDocs site that’s being served locally inside iSH. No extra devices, no external servers — just your iPad.

⚠️ Tip: Keep the iSH app running in the foreground (or in split-screen with Chrome/Safari). If iSH is fully sent to the background, iOS will freeze the process and your local MkDocs server will stop responding.

Final Thoughts

This little hack shows how powerful iSH can be. Pair it with MkDocs, and suddenly your iPad becomes a portable documentation lab. You can edit Markdown, rebuild instantly, and preview it live in your browser — all on one device.

⸻

👉 Would you try running MkDocs (or maybe even other Python-based tools) on your iPad?

Run MkDocs on iPad with iSH and Browse It Locally 🎉

Mohammed AlShannaq — Sat, 04 Oct 2025 01:29:02 +0000

How I Exported and Re-Imported a netcup Server Snapshot (raw.zst qcow2)

Mohammed AlShannaq — Thu, 25 Sep 2025 21:57:30 +0000

When you run servers on netcup (VPS or root Servers), one of the features you get is the ability to take snapshots of your VM. These snapshots can be downloaded as a file and stored locally or on object storage like S3, so you always have a backup you control.

In fact, one of the neat features netcup provides is the option to export snapshots as downloadable files. For many plans, a limited number of exports are included for free, and if you need more, you can purchase additional exports as an add-on.

This gives you the ability to keep offline or external copies of your VM state without relying solely on the built-in snapshot system — especially useful if you ever optimize storage or lose the snapshots stored within netcup’s platform.

🐛 But here’s the catch:

netcup lets you download snapshots in a compressed format:

vda_snapshot.raw.zst

However, when you try to re-upload the same .raw.zst back into netcup’s Server Control Panel (SCP), it fails. Why? Because netcup does not support .zst uploads — only raw, qcow, and qcow2 formats are officially supported and accepted.

In this article explains how I hit this problem, the dead ends I faced, and the working solution to restore my server successfully from a snapshot that I have created before for the server and downloaded it locally on my pc (or store it in AWS S3)

The Problem

I downloaded my snapshot from netcup: vda_alma10readysam1.raw.zst.
I wanted to re-import it via Upload Image → Generate Upload URL. (using netcup SCP) or even upload the image from my pc.
But when I tried to use it directly, and start the server after I receive email says that image installed, the server wouldn’t boot: “no boot device found.”

Why? After couple of tries I see that it happens because .raw.zst is only useful for downloading. netcup won’t accept it as an upload format.

Step 1: Decompress the Snapshot

First, you need to decompress the .zst file into a raw image. Install zstd if it’s missing:

💡 Note: The decompressed raw file will be the same size as your original VM disk (e.g. a 250 GB VM will produce a 250 GB raw file). Make sure you have enough free space on your system before starting the decompression.

First of all make sure zstd is insalled:

# AlmaLinux / Rocky
dnf install -y zstd

# Ubuntu / Debian
apt install -y zstd

Then decompress the .raw.zst file:

unzstd vda_alma10readysam1.raw.zst -o vda_alma10readysam1.raw

Now you have a .raw file.

⚠️ Warning: The raw file size always equals the full disk size of your VM. For example, if your VM had a 250 GB disk, the exported .raw file will be 250 GB — even if you only used 5 GB of actual data.
Trying to upload that 250 GB raw file would be a huge mistake: most of it is just empty space (zeros), so you’d be wasting time, bandwidth, and money moving around data that doesn’t really exist.

That’s exactly why converting to qcow2 is the smarter approach

Step 2: Convert Raw → qcow2

To save space and make uploads feasible, convert the raw image to qcow2. Install qemu-img if not already installed:

# AlmaLinux / Rocky
dnf install -y qemu-img

# Ubuntu / Debian
apt install -y qemu-utils

Convert the raw file:

qemu-img convert -p -O qcow2 vda_alma10readysam1.raw vda_alma10readysam1.qcow2

Now check the result:

qemu-img info vda_alma10readysam1.qcow2

Example output:

image: vda_alma10readysam1.qcow2
file format: qcow2
virtual size: 256 GiB (274877906944 bytes)
disk size: 7.01 GiB
cluster_size: 65536
Format specific information:
    compat: 1.1
    compression type: zlib
    lazy refcounts: false
    refcount bits: 16
    corrupt: false
    extended l2: false
Child node '/file':
    filename: vda_alma10readysam1.qcow2
    protocol type: file
    file length: 7.01 GiB (7531462656 bytes)
    disk size: 7.01 GiB

💡 Notice how the virtual size is still 256 GB, but the actual file size is just 7 GB. That’s the power of qcow2.

Step 3: Upload to netcup

Log into SCP → Media → Upload Image.
Click Generate Upload URL. (enter the file name for example vda_alma10readysam1.qcow2 ) and generate Upload Url, and the portal will give you Pre-signed URL to upload the file into using curl
Use curl or aws s3 cp to upload your qcow2 file:

url --progress-bar 'https://upload.url.from.netcup...fullurlofuploadurl...' --upload-file vda_alma10readysam1.qcow2 | cat

Once uploaded, select the image and deploy it to a new server.

After this, my server booted normally again 🎉.

👉 Note: You don’t have to use the Generate Upload URL method if you don’t want to. netcup’s SCP also allows you to upload the image directly from your local machine — simply browse for the .qcow2 file and upload it through the web interface. This can be easier for smaller images, but for larger files I still recommend using the upload URL approach.

Step 4: Store Your Snapshots Safely

Instead of keeping snapshots only in netcup, you can store them externally (after you export it)

This way, you can always re-import the image later, or even run it on another virtualization platform that supports qcow2 (Proxmox, KVM, etc.).

Lessons Learned

.raw.zst is download-only. You can’t re-import it to netcup.
You must convert it to raw, qcow, or qcow2 — with qcow2 being my most efficient choice.
Always verify your qcow2 image with qemu-img info before uploading.
Storing qcow2 snapshots externally (S3, local disk, NAS) makes disaster recovery much easier.

Conclusion

What started as a frustrating “no boot device 🤯” error turned into a neat learning experience. By decompressing and converting the snapshot, I was able to restore my VM cleanly and keep smaller, portable backups for the future.

To give you a sense of the savings:

The original snapshot (.raw.zst) was 4.6 GB.
After decompression to raw, it exploded to 256 GB (matching the full disk size).
Once converted to qcow2, it shrank back down to just 7.4 GB — small enough to store and upload efficiently.

If you’re running servers on netcup, don’t just rely on downloading .raw.zst snapshots. Convert them, back them up properly, and make sure you can re-import them when needed. Your future self will thank you.

DEV Community: Mohammed AlShannaq

[Boost]

Top 7 Featured DEV Posts of the Week

Jess Lee for The DEV Team ・ Nov 11

Run MkDocs on iPad with iSH and Browse It Locally 🎉

Step 1: Install iSH

Step 2: Install Python & Build Tools

Step 3: Install MkDocs

Step 4: Create a Project

Step 5: Serve the Site

Step 6: Browse on Your iPad 🎉

Final Thoughts

Run MkDocs on iPad with iSH and Browse It Locally 🎉

How I Exported and Re-Imported a netcup Server Snapshot (raw.zst qcow2)

The Problem

Step 1: Decompress the Snapshot

Step 2: Convert Raw → qcow2

Step 3: Upload to netcup

Step 4: Store Your Snapshots Safely

Lessons Learned

Conclusion