Backend API not responding on fresh 4CAT installation (Ubuntu 22.04, Docker)

[mifiwi]

Hello 4CAT team,

First of all, thank you for this great tool! I’m a relatively new user working on setting up 4CAT on a virtual machine (VM) using Docker. I’ve followed the installation guide, and while everything seems to be running, I’m having trouble getting the backend API to respond.

I’ve gone through extensive troubleshooting, including checking logs, network configurations, and container settings, but I’m stuck. I’d really appreciate any guidance!

I have installed 4CAT on a remote server (Ubuntu 22.04 LTS) using Docker and followed the official setup guide. The installation starts without errors, and all containers (backend, frontend, and database) appear to be running. However, the backend API does not respond to requests.

Despite multiple attempts to restart the backend and manually check configurations, the API remains inaccessible.

Steps to Reproduce:
1. Set up environment
• Running Ubuntu 22.04 LTS on a virtual machine (VM)
• Installed Docker and Docker Compose
• Cloned the latest version of 4CAT from GitHub
• Started services with:

docker-compose up -d

2.	Check running containers:

docker ps

•	All containers (backend, frontend, database) appear to be running.


3.	Check backend logs: 

docker logs --tail 50 4cat_backend

•	Logs indicate that the backend starts correctly and states: 

INFO at api.py:65: Local API listening for requests at backend:4444

•	But the API does not respond.


4.	Test API connection from within the backend container:

docker exec -it 4cat_backend curl -v http://localhost:4444/api/status

•	Result:

curl: (7) Failed to connect to localhost port 4444: Connection refused

5.	Checked firewall and network settings
•	UFW is inactive (sudo ufw status verbose → Status: inactive)
•	iptables rules allow traffic on port 4444
•	Docker network correctly assigns IPs (docker network inspect 4cat_default)


6.	Checked API worker process inside backend container:

docker exec -it 4cat_backend ps aux --width=200 | grep api

•	No API process is running.


7.	Checked API worker script (backend/workers/api.py)
•	The script is present but does not seem to be running as expected.

The backend should respond to API requests on port 4444, but rhe API does not respond, and curl requests fail with "Connection refused."

1.	Are there additional configuration steps needed for the API to function correctly?
2.	Is there a known issue with the API worker failing to start?
3.	Are there debugging steps we haven’t tried yet?

Any help or guidance would be greatly appreciated!

Thank you. 🙏

[dale-wahl]

It looks like the backend is at backend:4444 according to your log, so you could do something like curl http://backend:4444/api/status. You would see curl: (52) Empty reply from server though because that is not an endpoint.

• Something indeed may be off with your Docker setup as, curl http://localhost:4444 in a default docker setup would return Couldn't connect to server although from 4CAT's perspective that shouldn't be an issue.
• Note that backend:4444 only works inside the Docker network (e.g. inside a 4CAT container such as docker exec 4cat_backend curl backend:4444).
• You have mapped the public facing API (i.e., on your server/vm) to something in your .env file as the PUBLIC_API_PORT. That you could potentially use curl http://localhost:{whatever PUBLIC_API_PORT is set as}.

We have a call_api function in common.lib.helpers, so you could use that to help. The backend API does not really do much to be honest (the frontend mostly uses it to check statuses and interrupt running workers). Perhaps if you explain exactly are you trying to accomplish, we can be of more assistance.

There are some api endpoints from the frontend that users can use if they generate an API key to interact with 4CAT programatically. curl localhost:{PUBLIC_PORT from .env}/api/ There is an open issue to improve its documentation #459.