How to Embed FolkMQ in SpringBoot: A Tiny 7 MB Message Middleware

1. Understand FolkMQ Embedded Version

FolkMQ is a "pure‑blood" Chinese message middleware that supports embedded, standalone, cluster, and multi‑cluster deployments. The embedded version adds a web console and increases the size by only 7 MB, making it convenient for small projects that need messaging capabilities.

Key Points

Embedded mode works like H2 or SQLite, ideal for tiny or special‑requirement projects.

For larger projects you can use the standalone or cluster versions.

2. How to Integrate

Add two Maven dependencies to your project:

<code><dependency>
  <groupId>org.noear</groupId>
  <artifactId>solon.web.servlet.jakarta</artifactId>
  <version>2.8.3</version>
</dependency>
<dependency>
  <groupId>org.noear</groupId>
  <artifactId>folkmq-embedded</artifactId>
  <version>1.7.1</version>
</dependency></code>

Create a configuration class FolkMqConfig :

<code>package demoapp.folkmq;

@Configuration
public class FolkMqConfig {
    @PostConstruct
    public void start() {
        // start Solon with this config class
        Solon.start(FolkMqConfig.class, new String[]{});
    }

    @PreDestroy
    public void stop() {
        if (Solon.app() != null) {
            Solon.stopBlock(false, Solon.cfg().stopDelay());
        }
    }

    @Bean
    public FilterRegistrationBean folkmqAdmin() {
        // register servlet filter for http integration
        FilterRegistrationBean<SolonServletFilter> filter = new FilterRegistrationBean<>();
        filter.setName("SolonFilter");
        filter.addUrlPatterns("/folkmq/*");
        filter.setFilter(new SolonServletFilter());
        return filter;
    }
}
</code>

Add a folkmq.yml configuration file to control ports, tokens, and protocol, e.g.:

<code># server port
server.port: 8080
# token name to avoid conflicts
server.session.state.jwt.name: FOLKMQ-TOKEN
# console credentials
folkmq.admin: admin
# transport protocol (tcp or ws)
folkmq.schema: tcp
# transport port (default = server.port + 10000)
folkmq.transport.port: 0
</code>

3. Embedded Effect

After the application starts, the console is reachable at /folkmq/ .

4. Test the Integration

Run a client that connects to folkmq://localhost:18080 , subscribes to a topic, and publishes ten messages:

<code>public class ClientTest {
    public static void main(String[] args) throws Exception {
        MqClient client = FolkMQ.createClient("folkmq://localhost:18080")
            .nameAs("demoapp")
            .connect();
        client.subscribe("demo.topic", message -> {
            System.out.println(message);
        });
        for (int i = 0; i < 10; i++) {
            client.publish("demo.topic", new MqMessage("hello" + i));
        }
    }
}
</code>

The console will display the received messages as shown in the screenshot below.

5. Full Example Code

The complete SpringBoot 3 example can be found at https://gitee.com/noear/folkmq-embedded-examples/tree/main/folkmq-embedded-springboot3 .