docs: updated docker instructions

[bryanvaz]

Summary of changes:

• Updated DOCKER.md with new repository location
• Added link from README to DOCKER.md for Docker instructions
• Added Apple Silicon instructions (with caveat about tags)
• Added instructions for database persistence for dockerized instances
• Added sample docker compose file for non-production environments
• Added additional detail on environment variables used by dockerized version
• Fixed replica run command (see note below)

Rationale:

Spent the morning trying to figure out how to get Docker working in deterministic dev environments and ci pipelines. Required digging through source code and issues to realize the docker repo had moved, tags and arch were not the same as other dockerized DBs, and docker persistence documentation was hiding under the build instructions.

This additional documentation should help prevent others from experiencing the same consternation and hopefully reduce friction for adoption in more formal application development settings.

Additional Notes:

Replicas: Replica instructions were based on the original version of the doc and corrected for a typo in the environment variable flag; however I was not able to get the replica to handshake with the primary node. I'll open a separate issue with details on how to recreate.

Arm/Apple Silicon: Since, I assume, the dockerized version is provided out of convenience, but not officially supported by any formal effort, the arm64 is even less supported. As such, for now I've updated the instructions to recommend using Rosetta if on Apple Silicon, which will comprise the lionshare of the arm64 use-cases, and as release/stable versions only seem to be available in amd64.

[notrab]

From a docs formatting point of view, this is great work @bryanvaz! Thank you.

@penberg I'll defer to you guys to make sure the instructions are up to date. I don't see anything wrong personally, but you'll know better.

[notrab]

@bryanvaz I'm trying to figure out where more docs go in our docs.turso.tech site for libSQL. I think a new tab "libSQL" at the top of the page might be best that includes info on what libsql is, how to run it with Docker, deploy it, etc.

Let me know what you think!

[bryanvaz]

Thanks Jamie(@notrab)! Yea, based on the current state of libSQL and turso cli, a separate tab makes sense in that it properly delineates the Turso proprietary offering from the libSQL open source library.

However, looking at how the docs are setup right now and where Pekka has focused the internal development effort for the local development use-case, I think a more strategic rationalization needs to happen before you can answer the documentation question. Personally, I would say strategically it makes more sense to treat libSQL as part of a continuum, where libSQL is the "community"/self-hosted version, which flows into Turso cloud as the paid tier. You don't want to end up in a situation similar to Gitlab where you have a self-hosted "community" version that no one uses except FOSS evangelists, and a self-hosted "free" enterprise tier that everyone uses (either for scale, cost, or security reasons). MongoDB is probably one of the best examples of a well structured continuum, where it's borderline instinctual for dev teams to use Docker for deterministic local development, and deploy to either Atlas, or Enterprise.

Right now, turso dev occupies a weird middle ground where it can create and start a local turso/libSQL server, however the structure of the db files turso dev creates cannot be lifted and dropped into the location libSQL uses. The directory structure and file naming conventions are different; at least that's what I found out between turso version v0.88.8 and ghcr.io/tursodatabase/libsql-server:v0.22.22. In a continuum scenario, docker would just be another option for running locally, along side installing via homebrew or apt, and using the @libsql/client; so the docs would include docker as just another option in https://docs.turso.tech/local-development. Then the left hand sections in the docs would have one section for the client library, another for the libSQL server as if it was installed into the host OS environment, and a final section for a Dockerized version with specific details on how spin up dockerized primary and replica nodes, persistence and networking options, as well as env variables that can be passed in.

Finally, the docker tags are right now, not stable and do not behave how one would expect (right now on Feb 28, main is broken and does start). Ideally the pipeline should tag builds with expected behaviour as:

• latest: latest stable release version including minor patch
• v0.22: latest stable version pegged at a minor version, but latest patch under minor version
• v0.22.15: pegged version down to minor patch, does not change
• nightly or dev: the nightly build, or build that matches the dev branch (frequency depends on git velocity)
• main: the nightly build from the main branch, more stable than dev but not necessarily as stable as release.

Once those are pipeline issues and strategic considerations cleaned up, documentation should become alot easier.