atlas-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the-Drunken-coder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Atlas Core CLI
+
+`atlas-core` installs and operates one durable Atlas Core deployment on an arm64 or x64 macOS or Linux host with Docker Compose.
+The npm package is the operator interface. Atlas Core itself runs from the matching
+`ghcr.io/the-drunken-coder/atlas-core` container image.
+
+## Install
+
+Install Node.js 24 or newer and Docker with Compose 2.17.0 or newer, then install the CLI globally. The CLI requires a
+local Linux Docker daemon over a Unix socket; it refuses remote Docker contexts because the fixed deployment names and
+durable volumes belong to one host.
+
+```bash
+npm install --global atlas-core
+atlas-core init
+atlas-core start
+```
+
+`init` generates strong local credentials and provisions the MinIO bucket only when it can prove the deployment is
+new. It refuses to create new credentials over existing Atlas containers or volumes. Configuration is stored in `~/.atlas/core`
+with owner-only permissions. Set `ATLAS_CORE_HOME` before the first command to choose another location.
+
+## Commands
+
+```text
+atlas-core help
+atlas-core init
+atlas-core start
+atlas-core stop
+atlas-core restart
+atlas-core status
+atlas-core logs [core|postgres|minio] [--follow]
+atlas-core doctor
+atlas-core version
+```
+
+`stop` removes containers and the private Compose network. It preserves PostgreSQL and MinIO volumes. Removing the
+npm package also leaves those durable volumes untouched.
+
+The first release binds the Core API, PostgreSQL, and MinIO ports to loopback. It does not configure public ingress.
+Installing a different CLI version does not upgrade an initialized deployment. `start` and `restart` stop with an
+explicit version mismatch until a backup-aware upgrade path is available. Both commands require registry access and
+pull the release's digest-pinned image before starting; neither a locally retagged image nor an overwritten registry
+tag can replace the reviewed Core image.
+
+## External ingress
+
+Run Cloudflare Tunnel or another reverse proxy separately and route only the Core HTTP endpoint at
+`http://127.0.0.1:8000`. Atlas does not install the proxy or store its credentials. Follow the
+[external ingress guide](https://github.com/the-Drunken-coder/Atlas-Modernization/blob/main/docs/atlas-core/EXTERNAL_INGRESS.md)
+for CORS, command-interface configuration, readiness checks, and trusted-proxy behavior.
+
+## Storage safety
+
+PostgreSQL and the configured MinIO bucket are one durable store. Back them up and restore them together. The CLI
+never enables Core's destructive development startup mode and never passes `--volumes` to `docker compose down`.
+After the first full-stack start attempt, it refuses to recreate either durable volume if one goes missing. It also
+binds the state directory to the Docker engine that initialized it and verifies Docker Compose ownership labels before
+using an existing container or volume. Initialization also takes a Docker-engine-scoped project lock, so different
+configuration directories cannot initialize the same fixed deployment concurrently.
+
+If `init` finds existing Atlas volumes without its matching configuration, it stops. Do not delete those volumes to
+silence the check. Recover the credentials and paired storage instead.

package/assets/docker-compose.init.yml

@@ -0,0 +1,16 @@
+name: atlas_core_production
+
+services:
+  minio:
+    extends:
+      file: docker-compose.yml
+      service: minio
+
+volumes:
+  minio_data:
+    external: true
+    name: atlas_core_production_minio_data
+
+networks:
+  atlas_core_network:
+    driver: bridge

package/assets/docker-compose.yml

@@ -0,0 +1,126 @@
+name: atlas_core_production
+
+services:
+  api:
+    image: ${ATLAS_CORE_IMAGE:?ATLAS_CORE_IMAGE must be set by the atlas-core CLI}
+    container_name: atlas_core_production_api
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgres://atlas:${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}@postgres:5432/atlas_core
+      DATABASE_POOL_SIZE: ${DATABASE_POOL_SIZE:-5}
+      DATABASE_MAX_OVERFLOW: ${DATABASE_MAX_OVERFLOW:-10}
+      DATABASE_POOL_RECYCLE: ${DATABASE_POOL_RECYCLE:-3600}
+      DATABASE_POOL_TIMEOUT: ${DATABASE_POOL_TIMEOUT:-30}
+      DATABASE_POOL_IDLE_TIMEOUT: ${DATABASE_POOL_IDLE_TIMEOUT:-600}
+      DATABASE_POOL_PRE_PING: ${DATABASE_POOL_PRE_PING:-true}
+      DATABASE_RECREATE_ON_STARTUP: "false"
+      MINIO_ENDPOINT: minio:9000
+      MINIO_ACCESS_KEY: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
+      MINIO_SECRET_KEY: ${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set}
+      MINIO_BUCKET: ${MINIO_BUCKET:-atlas-media}
+      MINIO_SECURE: "false"
+      SERVER_PORT: "8000"
+      ENABLE_API_AUTH: "true"
+      CORS_ORIGINS: ${CORS_ORIGINS-}
+      CORS_ORIGIN_PATTERNS: ${CORS_ORIGIN_PATTERNS-}
+      TRUSTED_PROXY_CIDRS: ${TRUSTED_PROXY_CIDRS:-}
+      API_AUTH_KEY: ${API_AUTH_KEY:?API_AUTH_KEY must be set}
+      ATLAS_ADMIN_PASSWORD: ${ATLAS_ADMIN_PASSWORD:?ATLAS_ADMIN_PASSWORD must be set}
+      MAX_UPLOAD_SIZE_MB: ${MAX_UPLOAD_SIZE_MB:-100}
+      MAX_VIEW_SIZE_MB: ${MAX_VIEW_SIZE_MB:-10}
+    ports:
+      - "127.0.0.1:8000:8000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+      minio-init:
+        condition: service_completed_successfully
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/readiness"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    networks:
+      - atlas_core_network
+
+  postgres:
+    image: postgres:15@sha256:1b92e7a80c021647bf70f5d3eb66066a998e4f5cf43c07bb9dc9f729782cf88e
+    container_name: atlas_core_production_postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: atlas_core
+      POSTGRES_USER: atlas
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}
+      POSTGRES_INITDB_ARGS: "--auth-local=md5 --auth-host=md5"
+    command: ["postgres", "-c", "timezone=UTC"]
+    ports:
+      - "127.0.0.1:5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "PGPASSWORD=\"$$POSTGRES_PASSWORD\" pg_isready -U atlas -d atlas_core"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - atlas_core_network
+
+  minio:
+    image: minio/minio:RELEASE.2024-01-31T20-20-33Z@sha256:4092433a77e510826874b36f369696df43407a763d7f901a61d74e83e6fd95bc
+    container_name: atlas_core_production_minio
+    restart: unless-stopped
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set}
+    ports:
+      - "127.0.0.1:9000:9000"
+      - "127.0.0.1:9001:9001"
+    volumes:
+      - minio_data:/data
+    command: server /data --console-address ":9001"
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    networks:
+      - atlas_core_network
+
+  minio-init:
+    image: minio/mc:RELEASE.2024-01-31T08-59-40Z@sha256:c084c9a67c7a9ed5f37cc7f2a905010861aaa882bec76da10352305c9709b6d2
+    container_name: atlas_core_production_minio_init
+    restart: "no"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set}
+      MINIO_BUCKET: ${MINIO_BUCKET:-atlas-media}
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: /bin/sh
+    command:
+      - -c
+      - |
+        set -e
+        mc alias set atlas http://minio:9000 "$$MINIO_ROOT_USER" "$$MINIO_ROOT_PASSWORD" >/dev/null
+        mc stat "atlas/$$MINIO_BUCKET" >/dev/null
+        mc anonymous set none "atlas/$$MINIO_BUCKET"
+        echo 'MinIO bucket verified successfully'
+    networks:
+      - atlas_core_network
+
+volumes:
+  postgres_data:
+    external: true
+    name: atlas_core_production_postgres_data
+  minio_data:
+    external: true
+    name: atlas_core_production_minio_data
+
+networks:
+  atlas_core_network:
+    driver: bridge