Merge pull request #1 from gokhanercan/master

Added docker and ansible instructions

Author: kubarium

.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+.output
+dist
+*.log
+Dockerfile

.gitattributes

@@ -0,0 +1,8 @@
+*.sh text eol=lf
+Dockerfile text eol=lf
+
+# Data files (wordnets, dictionaries, corpora) must stay LF. The
+# nlptoolkit-dictionary loader splits on "\n" and uses the last token on each
+# line as a flag, so trailing CR breaks flag lookups like isProperNoun().
+*.txt text eol=lf
+*.xml text eol=lf

.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy to Guzel VPS
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:  # allow manual "Run workflow" from the Actions tab
+
+# The deploy SSH key is command-restricted on the VPS — it can only run
+# /root/deploy.sh — so even a leaked key cannot open a shell.
+# Secrets required on the repo:
+#   DEPLOY_SSH_KEY  - private key (ed25519) matching /root/.ssh/authorized_keys entry
+#   VPS_HOST_KEY    - a single known_hosts line (from ssh-keyscan -t ed25519 <host>)
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: deploy-guzel
+      cancel-in-progress: false
+    timeout-minutes: 10
+
+    steps:
+      - name: Configure SSH
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          echo "${{ secrets.DEPLOY_SSH_KEY }}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          echo "${{ secrets.VPS_HOST_KEY }}" > ~/.ssh/known_hosts
+          chmod 600 ~/.ssh/known_hosts
+
+      - name: Trigger deploy
+        run: |
+          # The key is pinned to command="/root/deploy.sh" on the server,
+          # so whatever we pass here is ignored. We pass `true` as a no-op.
+          ssh -o IdentitiesOnly=yes \
+              -i ~/.ssh/id_ed25519 \
+              -o UserKnownHostsFile=~/.ssh/known_hosts \
+              root@104.247.163.162 true
+
+      - name: Smoke test
+        run: |
+          # Poll the public endpoint until it returns 200 (startup ~30-60s).
+          for i in {1..60}; do
+            code=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 4 http://104.247.163.162:3000/ || true)
+            echo "attempt $i: HTTP $code"
+            if [ "$code" = "200" ]; then exit 0; fi
+            sleep 3
+          done
+          echo "::error::App did not return 200 within ~3 minutes"
+          exit 1

.gitignore

@@ -25,4 +25,5 @@ logs
 !.env.example
 
 # Project specific
-hunky-dory.xml
+hunky-dory.xml
+*.tar

AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+Guidelines for coding assistants working on this repository. Vendor-neutral — intended for any AI coding tool (Claude Code, Codex, Cursor, etc.).
+
+## Project overview
+
+Nuxt 3 (Vue 3) port of the Starlang NLP Toolkit. Runs as a single Node/Nitro server built from `Dockerfile`. Data files (wordnets, dictionaries, corpora) ship alongside the build — some at the repo root (copied into `.output/` by the Dockerfile) and some under `public/` (served as static by Nuxt).
+
+This is a fork of [kubarium/nlptoolkit](https://github.com/kubarium/nlptoolkit) maintained by [gokhanercan](https://github.com/gokhanercan). Fork-specific additions live in:
+
+- `Dockerfile`
+- `ops/` — ansible playbook, deploy notes
+- This file
+
+## Semantic versioning
+
+The project follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`).
+
+### Version file
+
+- **`package.json`** — the `"version"` field is the single source of truth. The UI reads it via `nuxt.config.ts` (`runtimeConfig.public.appVersion`) and renders it in the `NavBar` footer.
+
+### When to bump each number
+
+- **PATCH** (`1.0.0 → 1.0.1`): bug fixes, doc-only changes, dependency patch bumps, internal refactors with no observable behavior change.
+- **MINOR** (`1.0.1 → 1.1.0`): new features, new pages/tools, non-breaking additions to routes or components. Reset PATCH to `0`.
+- **MAJOR** (`1.1.0 → 2.0.0`): breaking changes — removed/renamed routes or APIs, schema changes, defaults flipped in user-visible ways. Reset MINOR and PATCH to `0`.
+
+When torn between MINOR and PATCH, **prefer PATCH**. Pre-release suffixes (`1.2.0-beta.1`) are allowed when needed.
+
+### Core rules
+
+1. **Always bump `package.json`'s `version` when you change application code, the Dockerfile, or ops scripts.** Comment-only or AGENTS.md-only edits can skip a bump.
+2. **Never skip numbers.** `1.0.3 → 1.0.4`, not `1.0.3 → 1.0.5`.
+3. **Never reuse a number.** Once shipped or tagged, that number is burned.
+4. **Never decrease a version.** Fix forward with a new PATCH.
+5. **Bump once per logical change**, not once per file.
+6. **Do not bump for CI/tooling/formatting-only changes.**
+
+### Workflow for a coding assistant
+
+When modifying code in this repo:
+
+1. Decide MAJOR / MINOR / PATCH based on the user-visible impact of the change.
+2. Update `package.json`'s `version` in the same commit as the code change.
+3. If you add a new file that also records a version (e.g. a new installer), list it here so future updates stay in sync.
+4. Do not create git tags unless the user asks.
+
+If uncertain about the bump level, ask before committing.
+
+## Build & run
+
+Three helper scripts at the repo root cover common workflows:
+
+- `./install.sh` — install pnpm (if missing) + project deps.
+- `./run.sh` — `pnpm dev`, Nitro on `:3000`. Ctrl+C to stop.
+- `./docker-run.sh` — `docker build` + `docker run` on `:3000`. Ctrl+C to stop (auto-removed).
+
+See `ops/readme.md` for the production deployment flow (docker save → scp → docker load on a remote host).
+
+## Upstream sync
+
+- Upstream is `kubarium/nlptoolkit` (remote name: `upstream`).
+- Fork is `gokhanercan/nlptoolkit` (remote name: `origin`).
+- When syncing upstream, prefer **merge** (not rebase) to avoid force-pushing the fork's public commits.

Dockerfile

@@ -0,0 +1,28 @@
+# Build stage
+FROM node:18 AS builder
+WORKDIR /app
+COPY . .
+RUN npm install -g pnpm@latest
+RUN pnpm install
+# Raise Node's heap ceiling for the Nitro build — default ~2GB OOMs on
+# this repo's data-file-heavy build. 4GB gives headroom on modest hosts.
+RUN NODE_OPTIONS=--max-old-space-size=4096 pnpm build
+
+COPY *.txt .output/
+COPY *.xml .output/
+
+# Runtime stage
+FROM node:18-alpine
+WORKDIR /app
+COPY --from=builder /app/.output .
+EXPOSE 3000
+CMD ["node", "server/index.mjs"]
+
+# Usage: 
+    # docker build -t nlptoolkit .
+    # docker run -p 3000:3000 nlptoolkit
+    # docker save -o nlptoolkit.tar nlptoolkit
+
+# # Install git
+# RUN apt-get update && apt-get install -y git
+# #RUN git clone https://github.com/gokhanercan/nlptoolkit /app

README.md

@@ -1,3 +1,13 @@
+# Install
+
+```bash
+npm install -g pnpm@latest-10
+pnpm i
+pnpm build
+node .output/server/index.mjs
+```
+
+
 # Nuxt Minimal Starter
 
 Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.

components/NavBar.vue

@@ -1,6 +1,8 @@
 <script setup lang="ts">
 import type { NavigationMenuItem } from '@nuxt/ui'
 
+const appVersion = useRuntimeConfig().public.appVersion
+
 const menu_labels = {
   "Turkish": {
     "Resources": ['FrameNet', 'PropBank', 'WordNet', 'SentiNet', 'Dictionary', 'Morphological Lexicon'],
@@ -63,9 +65,11 @@ const items = ref<NavigationMenuItem[][]>([
       color="secondary" />
 
     <a href="https://github.com/StarlangSoftware" target="_blank"
-      class="flex self-center items-center justify-self-end py-2 gap-4">
+      class="flex self-center items-center justify-self-end pt-2 gap-4">
       <img src="https://avatars.githubusercontent.com/u/61943048?s=48&v=4" alt="Starlang Software Logo">
       Starlang Software
     </a>
+
+    <p class="text-xs text-center text-gray-400 pb-2">v{{ appVersion }}</p>
   </header>
 </template>

docker-run.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Build the Docker image and run the app on :3000.
+# Foreground: Ctrl+C stops the container; it is auto-removed on exit.
+#
+# Usage: ./docker-run.sh   (from anywhere — cds into the repo first)
+set -euo pipefail
+
+cd "$(dirname -- "${BASH_SOURCE[0]}")"
+
+trap 'code=$?; echo ""; read -n 1 -s -r -p "Exited (code $code) — press any key to close..."; echo ""' EXIT
+
+IMAGE="nlptoolkit"
+NAME="nlptoolkit"
+
+echo "==> docker build -t ${IMAGE} ."
+docker build -t "${IMAGE}" .
+
+# Remove any previous foreground/detached container with the same name.
+docker rm -f "${NAME}" >/dev/null 2>&1 || true
+
+echo "==> docker run -p 3000:3000 (Ctrl+C to stop)"
+docker run --rm --name "${NAME}" -p 3000:3000 "${IMAGE}"

install.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Install pnpm (if missing) and this project's dependencies.
+#
+# Usage: ./install.sh   (from anywhere — cds into the repo first)
+set -euo pipefail
+
+cd "$(dirname -- "${BASH_SOURCE[0]}")"
+
+trap 'code=$?; echo ""; read -n 1 -s -r -p "Exited (code $code) — press any key to close..."; echo ""' EXIT
+
+if ! command -v pnpm >/dev/null 2>&1; then
+    echo "==> pnpm not found, installing pnpm@latest-10 globally via npm"
+    npm install -g pnpm@latest-10
+fi
+
+echo "==> pnpm install"
+pnpm install
+
+echo "==> done — run ./run.sh to start the dev server"