freeciv-web: the Freeciv client running in a browser through Tomcat and WebSockets

Five components, each in a different language

The overview section of the README breaks the project into five parts, and the language of each part is the fastest way to understand the design.

`freeciv-web` is the Java web application that makes up what each user's browser sees, implemented in JavaScript, Java, JSP, HTML and CSS, built with Maven, running on Tomcat 10 and nginx. The Metaserver, which is how the browser finds out which public servers exist, is part of this same module rather than a separate service.

`freeciv` is the actual game, the Freeciv C server, checked out from the official Git repository and patched to work with a WebSocket and JSON protocol. That is the key architectural fact: the game logic is not reimplemented in JavaScript, it is adapted.

`freeciv-proxy` is a WebSocket proxy, in Python, that lets WebSocket clients in freeciv-web send socket requests to Freeciv servers. The README traces the path explicitly: WebSocket requests go from JavaScript in freeciv-web to nginx, which proxies them to freeciv-proxy, which finally forwards them as Freeciv socket requests to the servers.

`publite2` is a Python process launcher that manages multiple Freeciv server processes and checks capacity through the Metaserver, and `pbem` is play-by-email support.

Two clients, one 2D isometric and one Three.js

There are two visualisations of the same game. The README describes an HTML5 2D version with isometric graphics and a 3D WebGL version, and there are separate screenshots for each in the project documentation.

The 3D version, called Freeciv WebGL, uses the Three.js engine, and the README links both a developer directory for it and a wiki page aimed specifically at 3D artists, titled Contributing Blender Models for Freeciv WebGL. That second link is the one worth following if you want to understand the art pipeline, because it tells you the models are made in Blender and the `blender/` directory in the repository tree is where that work lives.

A named developer is credited for the WebGL version, which is a small sign of how this project is organised: the 3D client has an identifiable owner, while the 2D client is simply the main client.

The game itself is described as turn-based, playable in any HTML5 capable browser, with the goal of building cities, collecting resources, organising your government and building an army. It also claims a wide variety of game modes, which the live server list below makes concrete rather than aspirational.

Three live public servers, with their modes named

The README lists the known public servers built on Freeciv-web, and says they are open source in compliance with the AGPL licence. That last clause is unusual and worth noticing: the servers are required to publish their own code.

The main community site is freecivweb.com, with its own repository, and the modes listed for it are single player, multiplayer, longturn, play-by-email and hotseat. FCIV.NET runs single player with WebGL graphics and has its own repository too. A third server, moving borders, is hosted on a Spanish domain and states plainly that it offers everything except longturn and real-Earth.

That list is more informative than it first appears. Longturn is a mode where a game advances at a fixed rate of one turn per interval regardless of players, which needs different infrastructure from ordinary multiplayer, so its absence from one server and presence on another tells you the two are not the same product. Real-Earth is a scenario using actual geography, and excluding it is a design choice about how the server is run rather than about the client.

Playing online is therefore a matter of picking a server and accepting its feature set, and the README's screenshots show the client is the same on all of them.

Getting it running with Vagrant, Docker, or by hand

The README recommends Vagrant on VirtualBox as the easiest route, and says it can create a local developer image running on the latest Ubuntu from a Windows, macOS or Linux host. The clone is shallow, which is the kind of detail that tells you the repository is large.

git clone https://github.com/freeciv/freeciv-web.git --depth=10

After cloning, `vagrant up` builds, compiles, installs and runs the whole thing on the virtual image, and you watch the log for errors. If you hit an error about virtualization not working, the README's advice is to enable VT in the BIOS.

vagrant up

Then point a browser at `http://localhost` on Windows or `http://localhost:8080` on Linux or macOS, and use `vagrant ssh` to get into the guest. The guest mounts your source repository in `/vagrant`. The README also states the resource floor: about 4GB of memory and 3GB of disk.

There is a warning for Windows users that deserves attention, because it is the kind of problem that eats an afternoon. The files are meant for a Unix-like system, editors on Windows may rewrite line endings, and that makes files unusable in the VM. There is some recovery during install but none afterwards, so the advice is to use dos2unix or an editor that respects Unix line endings.

The compose file tells you what the stack actually needs

The tree carries a `Dockerfile`, a `docker-compose.yml` and a `docker-entrypoint.sh`, and the compose file is more informative than the README's manual install list, which is showing its age.

The service is built from a `Dockerfile` on `debian:bookworm`, marked as version 3.3 of the Freeciv project, which already tells you this is a fairly recent image against old releases. It installs a set of packages with sudo and lsb-release, generates an en_US.UTF-8 locale, creates a `docker` user with passwordless sudo, copies in the `freeciv`, `freeciv-proxy`, `freeciv-web`, `pbem`, `publite2`, `scripts`, `music`, `blender` and `config` directories, then runs the project's own install script in TEST mode.

The port mapping is where the architecture becomes visible. The compose file publishes 8080 to 80, 4002, the ranges 6000 to 6009 and 7000 to 7009, and 8888 to 8080.

    ports:
      - "8080:80"
      - "4002:4002"
      - "6000-6009:6000-6009"
      - "7000-7009:7000-7009"
      - "8888:8080"

The paired port ranges are the tell: each Freeciv server process needs its own port, which is exactly why `publite2` exists as a launcher that manages several processes and reports capacity to the Metaserver. Anyone reading this compose file learns more about the deployment model than the README states in prose.

What the documentation has not caught up with

The manual install requirements list is where the age shows. It names Tomcat 10, which is current, alongside Java 11 JDK, Python 3.6, Pillow 2.3.0 as a PIL fork required for the image extraction tool, MariaDB, Maven 3, Firebug for debugging and a pinned curl 7.19.7.

Python 3.6 reached end of life years ago, and Firebug was superseded by Firefox developer tools long before that. So the manual path is best read as a historical inventory rather than a current checklist. If you are setting this up from scratch, the Dockerfile and the compose file are the documents to trust, since they are what actually gets built.

Releases reinforce the point. The two tagged releases are 3.0 from July 2015, described as the release to the production server, and 2.0 from July 2014. There has been no tagged release in about eleven years, while the repository itself is not archived, was last pushed on 2026-03-27, and has 2203 stars, 382 forks and 98 open issues.

So the project is alive and deployed, but versioned by commits rather than tags. Configuration lives in `config/config.dist`, which you copy without the `.dist` extension and edit, and the README says that is usually unnecessary unless you have specific requirements.

Editorial conclusion

freeciv-web is worth reading as architecture rather than as a game, because the interesting part is how a decades-old C server reaches a browser without being rewritten. The answer is a JSON and WebSocket protocol patch on the server, a Python proxy in front of it, nginx in front of that, and a Java web application on Tomcat 10 serving the client. That stack is old and deliberate, which means the same components deploy to production servers today. The two things to know before you start are the licence split, GPL for the C server and AGPL for the web client, and the divergence between documentation and reality, since the manual install list still names Python 3.6 and a browser debugging tool from 2018 while the tree carries a Dockerfile on Debian bookworm and a compose file. Use `docker compose up` if you can, follow the Vagrant path if you want the full install, and read `config/config.dist` before changing anything.

Frequently asked questions

Official sources

1. freeciv/freeciv-web on GitHub
2. Issues
3. README
4. Releases