Start a Single-Node or Container Lab, Connect with cqlsh, and Inspect Cluster Metadata

Learning outcomes

AtlasMart now has a version contract; the next risk is operational ambiguity. A container can be “running” while Cassandra is still initializing, port 9042 can be unreachable from the host because it was intentionally not published, and nodetool can fail for a JMX reason while CQL is healthy. This lesson builds a single-node lab whose process, configuration, storage, network and metadata are all observable.

1. Create the boundary before starting the database

The safest default for this course is an isolated Docker network. Running cqlsh and nodetool inside the container means neither CQL port 9042 nor JMX needs to be published to the host. A named data volume makes the persistence boundary visible. These choices reduce the blast radius while preserving the same Cassandra server semantics needed for the lesson.

docker network create atlasmart-cassandradocker volume create atlasmart-cass-1-datadocker run -d --name atlasmart-cass-1 --hostname atlasmart-cass-1 --network atlasmart-cassandra -e CASSANDRA_CLUSTER_NAME=atlasmart-course -e CASSANDRA_DC=dc1 -e CASSANDRA_RACK=rack1 -e CASSANDRA_ENDPOINT_SNITCH=GossipingPropertyFileSnitch -v atlasmart-cass-1-data:/var/lib/cassandra cassandra:5.0.9docker ps --filter name=atlasmart-cass-1docker inspect atlasmart-cass-1 --format '{{json .NetworkSettings.Networks}}'docker inspect atlasmart-cass-1 --format '{{json .Mounts}}' 

docker ps proves the container process is running. It does not prove Cassandra has finished bootstrapping or that native transport is accepting CQL. Cassandra startup is asynchronous and can take materially longer on a constrained laptop.

Readiness, not guessing

# Repeat until it succeeds; do not treat the first startup refusal as a permanent fault.docker exec atlasmart-cass-1 cqlsh -e "SELECT release_version FROM system.local;"# Inspect the most recent server messages if it does not succeed yet.docker logs --tail 120 atlasmart-cass-1

On Bash you may wrap the first command in a retry loop; in PowerShell use Start-Sleep and check $LASTEXITCODE. The course avoids a fixed “sleep 20 seconds” because startup time depends on CPU, storage and memory.

2. Inspect server, CQL and management identity

docker exec atlasmart-cass-1 cassandra -vdocker exec atlasmart-cass-1 java -versiondocker exec atlasmart-cass-1 cqlsh -e "SHOW VERSION"docker exec atlasmart-cass-1 cqlsh -e "DESCRIBE CLUSTER"docker exec atlasmart-cass-1 cqlsh -e "SELECT cluster_name, host_id, release_version, cql_version, data_center, rack, listen_address, partitioner FROM system.local;"docker exec atlasmart-cass-1 nodetool statusdocker exec atlasmart-cass-1 nodetool infodocker exec atlasmart-cass-1 nodetool describecluster

Record the actual output. Expected invariants are: the release identifies the pinned Cassandra patch; cluster metadata says atlasmart-course; topology says dc1/rack1; nodetool status reports one Up/Normal node after startup; and system.local exposes one node-local host ID. Token counts, load, addresses, schema version, uptime and heap values are machine-specific.

cqlsh exercises the CQL native transport. nodetool exercises management/JMX paths. One can fail while the other succeeds. That distinction matters when diagnosing “Cassandra is down”: a JMX authentication or port problem is not the same failure as a native-transport connection refusal.

3. Inspect configuration and storage without changing them

docker exec atlasmart-cass-1 sh -lc 'echo "$CASSANDRA_CONF"; grep -nE "^(cluster_name|listen_address|rpc_address|endpoint_snitch|authenticator|authorizer|native_transport_port|commitlog_directory|saved_caches_directory):" "$CASSANDRA_CONF/cassandra.yaml"'docker exec atlasmart-cass-1 sh -lc 'cat "$CASSANDRA_CONF/cassandra-rackdc.properties"'docker exec atlasmart-cass-1 sh -lc 'find /var/lib/cassandra -maxdepth 2 -type d | sort | head -60'docker exec atlasmart-cass-1 sh -lc 'ss -lnt 2>/dev/null | grep -E ":(7000|7001|7199|9042)\b" || true' 

The listening sockets are inside the container namespace. Docker's image metadata may expose ports without publishing them on the host. Verify host publication separately with docker port atlasmart-cass-1; the expected safe result for this lab is no host mapping. If you later need a host-native driver, publish only 127.0.0.1:9042:9042 for that exercise and keep JMX private unless the lesson explicitly secures and needs it.

4. Create AtlasMart state and prove every transition

docker exec atlasmart-cass-1 cqlsh -e "CREATE KEYSPACE IF NOT EXISTS atlasmart_lab WITH replication = {'class':'NetworkTopologyStrategy','dc1':1};"docker exec atlasmart-cass-1 cqlsh -e "CREATE TABLE IF NOT EXISTS atlasmart_lab.inventory_by_product (product_id text, warehouse_id text, quantity int, updated_at timestamp, PRIMARY KEY ((product_id), warehouse_id));"docker exec atlasmart-cass-1 cqlsh -e "SELECT keyspace_name, replication FROM system_schema.keyspaces WHERE keyspace_name='atlasmart_lab';"docker exec atlasmart-cass-1 cqlsh -e "SELECT keyspace_name, table_name FROM system_schema.tables WHERE keyspace_name='atlasmart_lab';"docker exec atlasmart-cass-1 cqlsh -e "INSERT INTO atlasmart_lab.inventory_by_product (product_id,warehouse_id,quantity,updated_at) VALUES ('p-1001','wh-baku',12,'2026-09-07T10:00:00Z');"docker exec atlasmart-cass-1 cqlsh -e "SELECT * FROM atlasmart_lab.inventory_by_product WHERE product_id='p-1001';"docker exec atlasmart-cass-1 cqlsh -e "UPDATE atlasmart_lab.inventory_by_product SET quantity=9, updated_at='2026-09-07T10:05:00Z' WHERE product_id='p-1001' AND warehouse_id='wh-baku';"docker exec atlasmart-cass-1 cqlsh -e "SELECT * FROM atlasmart_lab.inventory_by_product WHERE product_id='p-1001';"

The first query proves keyspace replication metadata, the second proves table existence, and the row queries prove application-visible state transitions. Cassandra writes are upserts: an UPDATE can create state even if the row did not previously exist. Chapter 06 treats timestamps, TTL, null/unset and mutation semantics in depth; do not import SQL row-existence assumptions into this lesson.

The partition key here is product_id, with warehouse_id clustering rows inside that product partition. This is intentionally small and pedagogical. It is not yet a defended production model: AtlasMart must later bound warehouses/cardinality, model required queries, measure hot products, and decide whether a different partition key or bucketing scheme is needed.

5. Diagnose three realistic failures

Failure A — Cassandra is still starting

A connection-refused error immediately after docker run does not prove an address error. Inspect logs and retry CQL readiness. Do not “fix” the situation by disabling security or changing random ports.

Failure B — host cqlsh cannot reach 9042

That is expected if you intentionally did not publish a host port. Use docker exec for the course lab. If a host-native driver is necessary, recreate the disposable node with a loopback-only mapping such as -p 127.0.0.1:9042:9042. Never use broad -p 9042:9042 as a reflex on an untrusted network.

Failure C — data vanishes after container replacement

If the node was started without the named volume, its writable container layer was the persistence boundary. The repair is to use the explicit course volume and verify the mount with docker inspect. Do not conclude that Cassandra persistence failed; the container-storage design failed.

Verification checklist

• Container is running and CQL readiness succeeds.
• system.local reports the intended cluster/DC/rack and exact Cassandra release.
• nodetool status/info can query management state.
• No CQL or JMX port is published on the host in the default lab.
• The named data volume is mounted at the Cassandra data boundary.
• AtlasMart keyspace/table/row state can be re-read deterministically.

Cleanup/reset

docker exec atlasmart-cass-1 cqlsh -e "DROP KEYSPACE IF EXISTS atlasmart_lab;"docker rm -f atlasmart-cass-1# Remove the volume only when you intentionally want a full data reset.docker volume rm atlasmart-cass-1-datadocker network rm atlasmart-cassandra

Production judgment

A healthy single node is a useful syntax and storage-path laboratory, not a Cassandra production architecture. It has no replica failure tolerance, shares one failure domain, and leaves repair/failover behavior untested. Its value is observability: every later multi-node claim can now be compared with known server, CQL, JMX, storage and topology evidence.

The final lesson scales this exact lab—not a new naming scheme—to three nodes, RF=3, explicit racks, QUORUM operations, and reversible node failures.

Summary and next step

This lesson’s concepts, evidence path, failure boundaries, and production judgment should now be explicit enough to verify rather than assume. Re-run the check-your-understanding prompts and preserve any lab evidence you need before changing or cleaning up the environment.

Next, continue to Build a Safe Course Lab with Multiple Nodes, Sample Keyspaces, Metrics, and Repeatable Failure Tests.

Authoritative references

• Apache Cassandra 5.0 documentation — Current official documentation entry point for the 5.0 line.
• Apache Cassandra downloads — Official release page used to verify the current 5.0 patch.
• Cassandra architecture overview — Official architecture and wide-column/distributed design framing.
• Cassandra quickstart — Official Docker-oriented learning workflow and isolated-network approach.
• Cassandra configuration reference — Official cassandra.yaml semantics, including native transport and security-related settings.
• CQL querying and cqlsh — Official CQL/cqlsh connection and system.local examples.
• Java support for Cassandra 5.0 — Official Java build/runtime compatibility notes for Cassandra 5.0.
• Docker Official Image: Cassandra — Container-image usage and tag information for the Docker Official Image.