The woodpecker-ci documentation is extremely misleading,docker compose + http setup

[1puls2is3]

As a first time woodpecker-ci user, the following documentation was very misleading for me.

First of all it is probably very important to note that I am using http, not https, and this is probably the most important reason.

1. https://woodpecker-ci.org/docs/administration/deployment-methods/docker-compose

docker-compose 
    ports:
      - 8000:8000
    environment:
      - WOODPECKER_HOST=${WOODPECKER_HOST}
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000

I don't know what port 8000 is used for, it doesn't say anything about it in the documentation on this page.
WOODPECKER_SERVER=woodpecker-server:9000 has a port number.
WOODPECKER_HOST=${WOODPECKER_HOST} , there is no port number, and the name of this environment variable is HOST, so there should be no port number here, otherwise it would be HOST:PORT.

So I assume that WOODPECKER_HOST should not have a port number.
And if it does, I don't know what the correct port number is, because the documentation doesn't say anything about it.

But actually WOODPECKER_HOST needs to be configured with the default port 8000.
This is very confusing!

2. https://woodpecker-ci.org/docs/administration/forges/gitea#registration

It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with **https://<host>/authorize** as the path.

Based on the documentation, I would assume that it should be configured without a port number, but in fact it needs to be configured with a port number, or by modifying the docker compose configuration file.

3. https://woodpecker-ci.org/docs/administration/server-config#woodpecker_server_addr

WOODPECKER_SERVER_ADDR
Default: :8000

Configures the HTTP listener port.

As a first time woodpecker-ci user, I have no idea what the default port 8000 is for, and why is it WOODPECKER_SERVER_ADDR and not WOODPECKER_SERVER_PORT?
According to the description, isn't it configured for PORT?

These problems have caused me to be unable to configure the callback URL correctly in gitea.

I think it's important for anyone who wants to try it out to do so in as simple a way as possible.
The docker compose and http are definitely the ones that require the least amount of work.
But this documentation builds a 100 meter high wall around the easiest way to learn about woodpecker-ci, making it impossible to take the first step forward.

I'd HOPE to see in the next major release, say 3.0, a reorganization of names like WOODPECKER_SERVER_ADDR to make them more accurate.

I think that documentation is very important, no less important than code for any software project.

Maybe I'm greatly misunderstanding all this, if so, please point it out, thank you very much!

[zc-devs]

I have no idea what the default port 8000 is for

https://woodpecker-ci.org/docs/usage/terminology

Server: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration.
Agent: A component of Woodpecker that executes pipelines with a specific backend. It connects to the server via GRPC.

https://woodpecker-ci.org/docs/usage/terminology#woodpecker-architecture
So, HTTP port (8000 by default) is used for all things except Agent-Server GRPC link.

why is it WOODPECKER_SERVER_ADDR and not WOODPECKER_SERVER_PORT?
According to the description, isn't it configured for PORT?

Because it is like Apache or Nginx listen directive.

# WOODPECKER_HOST=http://woodpecker.example.org WOODPECKER_GITEA=true /bin/woodpecker-server
# netstat -tulpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 :::9000                 :::*                    LISTEN      193/woodpecker-serv
tcp        0      0 :::8000                 :::*                    LISTEN      193/woodpecker-serv

# WOODPECKER_HOST=http://woodpecker.example.org WOODPECKER_GITEA=true WOODPECKER_SERVER_ADDR=127.0.0.1 /bin/woodpecker-server
ERR http server failed error="listen tcp: address 127.0.0.1: missing port in address"

# WOODPECKER_HOST=http://woodpecker.example.org WOODPECKER_GITEA=true WOODPECKER_SERVER_ADDR=127.0.0.1:8000 /bin/woodpecker-server
# netstat -tulpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 127.0.0.1:8000          0.0.0.0:*               LISTEN      319/woodpecker-serv
tcp        0      0 :::9000                 :::*                    LISTEN      319/woodpecker-serv

# ip addr
11: eth0@if12: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP 
    link/ether 02:42:ac:11:00:02 brd ff:ff:ff:ff:ff:ff
    inet 172.17.0.2/16 brd 172.17.255.255 scope global eth0
       valid_lft forever preferred_lft forever
# WOODPECKER_HOST=http://woodpecker.example.org WOODPECKER_GITEA=true WOODPECKER_SERVER_ADDR=172.17.0.2:8001 /bin/woodpecker-server
# netstat -tulpn
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 172.17.0.2:8001         0.0.0.0:*               LISTEN      420/woodpecker-serv
tcp        0      0 :::9000                 :::*                    LISTEN      420/woodpecker-serv