added new document for Ubuntu + nginx + WebSockets + more

[the-webb-identity]

No description provided.

[greptile-apps]

Greptile Summary

This PR adds a new 794-line guide for running Shadowsocks-over-WebSockets behind a fake HTTPS website on Ubuntu with nginx, certbot, and No-IP DDNS. The setup is well-structured and covers the full stack end-to-end, but there are several blocking correctness issues:

• Wrong DUC package: the ARM64 example installs armhf (32-bit ARM) instead of arm64.
• Missing sudo on the noip-duc symlink creation in /etc/systemd/system/.
• Missing systemctl daemon-reload before both service enable/start calls (noip-duc and outline-ss-server).
• yq v3/v4 incompatibility: the management script uses --yaml-output and --exit-status flags from yq v3, but apt-get install yq on Ubuntu installs yq v4 (Go), making the entire script non-functional.

Confidence Score: 3/5

Not safe to merge as-is — multiple P1 issues will cause the documented steps to fail for readers following them exactly.

Four independent P1 defects (wrong .deb architecture, missing sudo, missing daemon-reload ×2, yq version incompatibility) mean key steps in the guide will produce errors when followed literally. The yq issue in particular makes the entire optional management script completely broken on the target platform.

docs/vpn/advanced/ubuntu-nginx-websockets.md — especially the noip-duc install section (lines 130–163), the outline-ss-clients script (lines 252–391), and the outline-ss-server service setup (lines 516–521)

Important Files Changed

Filename	Overview
docs/vpn/advanced/ubuntu-nginx-websockets.md	New 794-line setup guide for Shadowsocks-over-WebSockets on Ubuntu+nginx; has 4 P1 issues: wrong architecture package (armhf vs arm64), missing sudo on noip-duc symlink, missing daemon-reload for both services, and yq v3/v4 version incompatibility that makes the management script entirely non-functional

Sequence Diagram

sequenceDiagram
    participant C as Outline Client
    participant DNS as DNS / DDNS
    participant NX as nginx (443 SSL)
    participant SS as outline-ss-server (127.0.0.1:4444)

    C->>DNS: Resolve fake-website.com
    DNS-->>C: Server IP

    C->>NX: HTTPS GET /clients/client-id.yaml
    NX-->>C: ssconf YAML (cipher, secret, wss:// URLs)

    C->>NX: WebSocket Upgrade wss://fake-website.com/path/tcp
    NX->>SS: HTTP/1.1 Upgrade (proxy_pass)
    SS-->>NX: 101 Switching Protocols
    NX-->>C: 101 Switching Protocols

    C->>NX: Shadowsocks TCP traffic (encrypted)
    NX->>SS: Forwarded WebSocket frames
    SS-->>NX: Response frames
    NX-->>C: Shadowsocks TCP response

    C->>NX: WebSocket Upgrade wss://fake-website.com/path/udp
    NX->>SS: HTTP/1.1 Upgrade (proxy_pass)
    SS-->>NX: 101 Switching Protocols
    NX-->>C: 101 Switching Protocols

    C->>NX: Shadowsocks UDP traffic (encrypted)
    NX->>SS: Forwarded WebSocket frames
    SS-->>NX: Response frames
    NX-->>C: Shadowsocks UDP response

Loading

_{Reviews (1): Last reviewed commit: "added new document for Ubuntu + nginx + ..." | Re-trigger Greptile}

[greptile-apps]

yq version incompatibility — script is non-functional on Ubuntu

Step 2.1 installs yq via apt-get install yq. On Ubuntu (18.04+), this installs yq v4 (the Go-based tool by Mike Farah), which does not have a --yaml-output flag and has completely different expression syntax. The --yaml-output and --exit-status flags used throughout this script are from yq v3 (the Python-based tool by kislyuk), which is no longer in Ubuntu's main repos.

Every yq call in this script will fail with unknown flag: --yaml-output, making the entire client management script non-functional. Either the doc should install the correct yq version explicitly, or the yq invocations need to be rewritten for v4 syntax.

[the-webb-identity]

this has all been tested and it works fine

[the-webb-identity]

@ohnorobo please review

[ohnorobo]

Hey @the-webb-identity thanks for writing all this up!

I've pushed this to https://developer.getoutline.org/vpn/advanced/ubuntu-nginx-websockets/ so you can see it with the final formatting applied. Currently it's not linked from the sidebar or the other pages.

Overall I think for the formatting looks a bit odd on the final site, and should be updated to more closely match the other articles. Some things that specifically stand our to me are:

• The Note sections, these don't need to have the text "ℹ️ Note:", and be quoted.
• Too much bullet point nesting. It makes the article difficult to read. Prefer to keep most of the article content unnested and use # header sections to differentiate various sections. You can use something like markdown's :::tip or :::warning styles.
• Various small formatting things like capitalizing list items.

Please also remove the client management script pieces for now. Having that amount of code stored in documentation won't work well for us. But maybe some of those improvements could be ported back to outline-ss-server?