Flamingo IM: a C++11 instant messaging stack you compile yourself

What flamingo actually gives you: three servers and two clients

Flamingo IM is an open source instant messaging stack written in C++11. The repository holds a server side, a PC client and an Android client, and the README states that a WeChat version and an iOS version are still under development. That sentence is the honest scope line: the shipped surface is Linux servers plus a Windows desktop client plus an Android app.

The feature list is the ordinary set you would expect from a teaching-grade IM: registration, login, friend and group search, friend and group lists, recent conversations, one-to-one chat with text, emoji, window shake and offline files, group chat with text and emoji, broadcast messages, password change, profile editing with custom nickname, signature and avatar, auto-upgrade, and reconnect after a dropped connection. The README also mentions client-side details it does not enumerate, such as three avatar display modes, a friend-online animation, chat history and automatic replies.

The audience is narrow and specific. This is for engineers who want to study or fork a working messaging backend, and for teams that need a starting point they can modify rather than a service they can call. It is not for anyone who wants a messaging feature in a product next week, because there is no hosted endpoint, no package manager entry, and no release artifact in the repository.

How the server side splits into chatserver, fileserver and imgserver

The build produces three executables, and the README describes them as mutually independent processes that you can start separately or as daemons. chatserver handles registration, login and chat. fileserver handles offline file transfer inside a chat window and the download of client auto-upgrade packages. imgserver handles images sent in chat and the upload and download of custom avatars.

That split is the architecture. There is no message broker and no shared service registry in the README; the three processes are separate binaries with separate listening ports. The port table is the clearest map of the system: chatserver listens on 20000 for chat, 8888 for a monitoring console, and 12345 for HTTP short connections. fileserver listens on 20001. imgserver listens on 20002. The README notes that the chat service supports long connections and also HTTP short connections, which is why 12345 exists alongside 20000.

The 8888 port is the part worth copying. Connect with nc and you get a small text console with three commands: help, ul to list online users, and su [userid] to show one user's information. The README shows the session and then says you can add more commands. For a project of this shape, a telnet-readable status port is a better operational story than a metrics endpoint nobody wired up.

Persistence is MySQL. The chat service reads its database name, username and password from flamingoserver/etc/chatserver.conf. On first start it checks whether the flamingo database exists, creates it if not, checks the tables, and creates them if not. The README warns that SQL syntax differs slightly between MySQL versions, so table creation may fail, in which case you run the statements in flamingoserver/table.sql by hand. The tables named in the README are t_user for user information, t_user_relationship for friend relationships and group membership, and t_chatmsg for chat history.

Building flamingo on Linux: cmake, make, and the first start

The README targets Linux, recommends CentOS 7.0 or later, and requires gcc/g++ 4.7 or above with 4.8.5 recommended, because the server code is pure C++11. cmake and make are the build tools. For the database, CentOS 7 and later should install mariadb-server, mariadb-client and mariadb-devel; other distributions should install mysql-server, mysql-client and mysql-devel.

Build from the flamingoserver directory. The first command generates a Makefile, and the second produces the three executables.

cd flamingoserver
cmake .
make

After a successful make you should have chatserver, fileserver and imgserver. Start them in the foreground, or add -d to run each as a daemon:

./chatserver -d
./fileserver -d
./imgserver -d

Check that the expected ports are listening. The README uses lsof for this and shows chatserver holding 20000, 8888 and 12345, fileserver holding 20001, and imgserver holding 20002.

lsof -i -Pn

Then connect to the monitoring port to confirm the chat service is alive. The README's example uses nc with -v, which asks for verbose output.

nc -v 127.0.0.1 8888

At that prompt, ul lists online users and su [userid] shows one user. If the database is empty, ul answers "No user online." and su without an argument answers "please specify userid." That is the expected first-run state, not an error.

For the PC client, open Flamingo.sln under flamingoclient/ in Visual Studio 2019. The solution contains the main client, CatchScreen for screen capture, and iUpdateAuto for unpacking auto-upgrade zips. Build output lands in flamingoclient/Bin, and the server connection settings live in flamingoclient/Bin/config/flamingo.ini. Run Flamingo.exe to start. For Android, open the flamingoAndroid project in Android Studio, build flamingo.apk, and set the server address on the login screen's server settings.

Where flamingo will fail you: the licence file and the missing platforms

The most concrete limitation is legal, not technical. The repository listing shows no licence file at the top level, and the metadata records the licence as unknown. For a project you intend to fork into a product, that is a blocker you resolve before writing code, not after. Nothing in the README grants rights, and the README does not discuss licensing at all.

The second limitation is platform coverage. The README says the WeChat version and the iOS version are under development, so anyone who needs an iPhone client is out of scope today. The PC client is a Visual Studio 2019 solution, which means the desktop path runs through Windows and MSVC rather than cmake on macOS or Linux.

The third is the database bootstrap. Automatic creation of the flamingo database and its tables is convenient until it silently diverges from what your MySQL version accepts. The README itself flags this and points at flamingoserver/table.sql as the fallback. Treat the automatic path as a convenience and the SQL file as the source of truth.

Finally, the README is the specification. There is no API reference for the wire protocol beyond the repository's own notes, and no documented rollback procedure for a schema change. The bug policy in the README is a personal commitment with stated windows, three working days for crashes and two weeks for other functional bugs, not a service level agreement. If your use case requires a support contract, flamingo is the wrong tool.

flamingo against a general C++ server framework

The README makes a claim that is easy to skim past: the server code is not only the backend of an IM application, it is also a general C++11 server framework. That reframes the comparison. The realistic alternative for most readers is not another chat product but a general-purpose C++ networking framework such as muduo, or a full messaging platform such as Matrix with its own homeserver implementation.

The difference in approach is what you get out of the box. A general framework gives you event loops, buffers and connection management, and you write the protocol, the persistence layer and the business logic. flamingo hands you the whole vertical slice: a wire protocol with long and short connection modes, MySQL-backed user, relationship and message tables, three cooperating services split by payload type, and two clients that already speak to it. The trade is that you inherit its choices. The database is MySQL, the schema is the three tables named in the README, and the message format is whatever the repository's notes describe rather than a published standard.

A platform like Matrix goes the other way: federation, a specified protocol, and clients you did not write, at the cost of running a much larger system and accepting an ecosystem's decisions. flamingo sits between the two. It is a complete application you can read end to end, which is rare, and it is not a standard anyone else implements.

Maintenance, upgrades and what the repository tells you about cost

The repository is not archived. The last push was on 2026-04-15. The README addresses cadence directly: the author writes that regular work makes a fixed release cycle impossible, and commits to maintaining the project. There are no retrieved releases, so there is no versioned artifact to track and no changelog file to diff against. The README points to an issue for the update log instead, and the repository root carries several plain text logs, including 更新日志.txt and 服务器端更新日志.txt.

Upgrade cost follows from that. Without releases, an upgrade means pulling the master branch and rebuilding all three server binaries with cmake . and make. Client upgrades are not something you schedule: the README lists auto-upgrade as a feature, with fileserver serving the upgrade packages and iUpdateAuto unpacking them on Windows, so the update channel is part of the application rather than something you bolt on.

The schema is the part that will bite. Because chatserver creates the flamingo database and its tables on first start, a change to the table definitions only takes effect on a fresh database unless you apply it yourself. The README does not document a migration path, and flamingoserver/table.sql is the only schema artifact named. Plan to manage that file yourself.

On licensing: the repository shows no licence, and the metadata records it as unknown. That is a fact about the repository, not legal advice. If you intend to redistribute flamingo or ship it inside a product, get the question answered before you build on it.

Editorial conclusion

Adopt flamingo if you want to read or extend a complete C++11 messaging backend: the three services are independent, the ports are documented, and the PC client opens from a checked-in Visual Studio 2019 solution. Do not adopt it if you need a supported product, a published licence, or an iOS or WeChat client, since the README says those are still being developed and the repository carries no licence file. Verify three things before you commit: that your MySQL or MariaDB version accepts flamingoserver/table.sql, that cmake . followed by make produces chatserver, fileserver and imgserver on your compiler, and that the connection settings in flamingoclient/Bin/config/flamingo.ini point at your host.

Frequently asked questions

Official sources

1. balloonwj/flamingo on GitHub
2. Issues
3. README