diff --git a/assets/social-logo.png b/assets/social-logo.png index 7c9a5ab..54bd9db 100644 Binary files a/assets/social-logo.png and b/assets/social-logo.png differ diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index f0ca6e3..cd4be98 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -1,6 +1,6 @@ import { defineConfig } from 'vitepress' -import { repository, version } from '../../package.json' +import { devDependencies, version } from '../../package.json' import navbar from './navbar.mjs' import { SidebarItems } from './sidebar.mjs' diff --git a/docs/.vitepress/navbar.mjs b/docs/.vitepress/navbar.mjs index 3ace41e..94f0fad 100644 --- a/docs/.vitepress/navbar.mjs +++ b/docs/.vitepress/navbar.mjs @@ -14,7 +14,7 @@ function getItems(version) { return [ { text: 'Home', link: '/' }, - { text: 'Examples', link: '/markdown-examples' }, + { text: 'Guide', link: '/guide/about' }, { text: nver, items: [{ text: 'Changelog', link: '/changelog' }], diff --git a/docs/.vitepress/sidebar.mjs b/docs/.vitepress/sidebar.mjs index 1936170..253ae72 100644 --- a/docs/.vitepress/sidebar.mjs +++ b/docs/.vitepress/sidebar.mjs @@ -1,7 +1,15 @@ export const SidebarItems = { - text: 'Examples', - items: [ - { text: 'Markdown Examples', link: '/markdown-examples' }, - { text: 'Runtime API Examples', link: '/api-examples' }, - ], + '/guide/': { base: '/guide/', items: getGuide() }, +} + +function getGuide() { + return [ + { + text: 'Guide', + items: [ + { text: 'About', link: '/about' }, + { text: 'Getting Started', link: '/getting-started#Quickstart' }, + ], + }, + ] } diff --git a/docs/guide/about.md b/docs/guide/about.md new file mode 100644 index 0000000..4e0fa3c --- /dev/null +++ b/docs/guide/about.md @@ -0,0 +1,107 @@ +# What is Arkanum + +### 🚀 Starship prompt + +We added the [Starship](starship.rs) prompt is as default in the integrated terminal. The default config uses Emojis and FiraCode icons. + +### 🔱 git config + +Added default git system config file with: + +- code-server as default editor. +- disabled `aurocrlf`. +- enabled plain credential store for remote. +- added git log helper `lg1` + `lg2`. +- enabled bash completion for git command in integrated bash terminal. + +> 💡 See [gitconfig-system](./gitconfig-system) for details. + +### 🧙 `arkanum` helper + +Added `arkanum` to help installing common runtimes in container. +This helps reducing the image size. + +``` +🧙 arkanum ✨🌌☄️💥 is used to install optional tools for developing in a + code-server container environment. + + Syntax: arkanum COMMAND OPTION ARGUMENT + COMMAND + config The config command is used to modify arkanum itself. + git The git command is a wrapper for git helpers. + install The install command is used to add different tools + help Shows this help text. + + OPTION + config: + disable-motd Disables hint in new bash terminal. + install extensions Installs predefined recommended extensions. + reset-codesettings Sets VS Code user setting with basic (Fira Code). + + git: + setup Takes two arguments to setup the git client: + 1) Username + 2) Email address + + install: + docker-cli Installs the latest docker-cli. + dotnet Installs latest LTS dotnet core sdk + runtime. + gitea Installs gitea tools like the changelog generator. + golang Installs golang 1.19.3. + bun Installs latest bun version. + nodejs Installs latest NodeJs LTS version using Volta. + volta Installs Volta as NodeJS version manager. + powershell Installs latest PowerShell LTS version. + + Example 1: arkanum git setup "my-name" "my-email" + Example 2: arkanum install golang + Example 3: arkanum config disable-motd +``` + +### 📝 Fira Code (NerdFont patched) + +Added FiraCode as default font in editor and integrated terminal. The font files are embedded and can be used without local installation. + +### 🦸 VSCode default settings + +If your start the container or log in the first time, a default config file is deployed. + +This user setting defines the following stuff: + +- Use compact menu bar to avoid users with multiple menu bars. +- Use _One Dark Pro Darker_ theme +- Use _vscode-icons_ icon set +- Set FiraCode as default font in editor. + - Tries to use alternate font names for FiraCode if its locally available. +- Sets FiraCode mono variant in terminal to enable icons used by starship prompt. +- Enables font ligatures +- Enables _auto save_ and _format on save_. +- Disables auto update for extension. +- Disables VSCode telemetry +- Disable confirm message for sync branches. + +Additionally we install these extensions on container startup: + +- [One Dark Pro](https://open-vsx.org/extension/zhuangtongfa/material-theme) theme +- [vscode-icons](https://open-vsx.org/extension/vscode-icons-team/vscode-icons) icon set +- [Gitlens](https://open-vsx.org/extension/eamodio/gitlens) + +## 💣 Known Issues + +### Starship.rs + +Starship detects workspaces as active python projects. It always appends the prompt +fragment `via 🐍 (lsiopy)`. For now I disabled the python module in starship. + +### 🐛 Default extensions installation timing error + +If the automatic installation of the default extension fails, you can always retry he installation with the +following command: + +```bash +# restart the installation +arkanum config install-extensions +# Optional: reset the vscode user setting +arkanum config reset-codesettings +# Reload with command F1 + Developer: Reload Window +``` diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md new file mode 100644 index 0000000..8f86421 --- /dev/null +++ b/docs/guide/getting-started.md @@ -0,0 +1,138 @@ +# Getting Started + +## Installation + +### Prerequisites + +Any host with either + +- Docker CE / EE running +- or Docker-CE and configured 'swarm' mode. + +### 1. ⚡ Get the image 📦 + +You can download the image from the gitea embedded container registry: `gitea.ocram85.com/codeserver/arkanum` with these tags: + +- `latest` - Is based on the lasted master branch commit. +- `next` - Is a test build based on the pull request +- `1`, `0.1`, `0.1.0`, `1.0.0` - tag based version. + +> **💡 NOTE: See the [packages page](https://gitea.ocram85.com/CodeServer/-/packages/container/arkanum/latest) for latest version and all other available tags.** + +The container images are also published to these registries: + +- [Docker Hub](https://hub.docker.com/r/ocram85/arkanum) + - Pull Endpoint: `ocram85/arkanum` +- [GitHub Container Registry](https://github.com/OCram85/arkanum/pkgs/container/arkanum) + - Pull Endpoint: `ghcr.io/ocram85/arkanum` +- [Codeberg Packages](https://codeberg.org/codeserver/-/packages/container/arkanum/next) +- Pull Endpoint: `codeberg.org/codeserver/arkanum` + +### 2.a Run as Docker Swarm Stack + +This example shows how to run arkanum as an additional swarm stack. + +Therefore you need + +- an already running docker swarm cluster, +- a running traefik instance handling the http and https routes, +- configured to expose services in the a ingress overlay network called `traefik-public`. + +> ❗ **Warning:** Make sure to secure the access to arkanum with proper **authentication method** and use +> a trusted + **secure https connection**. + +```yaml +version: "3.8" +services: + arkanum: + image: gitea.ocram85.com/codeserver/arkanum:1.0.0 + environment: + - PUID=1000 + - PGID=1000 + - TZ=Europe/Berlin + - PASSWORD=foo #optional + #- HASHED_PASSWORD= #optional + - SUDO_PASSWORD=foobar #optional + #- SUDO_PASSWORD_HASH= #optional + #- PROXY_DOMAIN=code-server.my.domain #optional + - DEFAULT_WORKSPACE=/config/workspace + deploy: + replicas: 1 + labels: + - "traefik.enable=true" + - "traefik.docker.network=traefik-public" + - "traefik.http.routers.arkanum.rule=Host(`vscode.mydomain.com`)" + - "traefik.http.routers.arkanum.tls.certresolver=myresolver" + - "traefik.http.services.arkanum-srv.loadbalancer.server.port=8443" + volumes: + # store workspace and use config in volume. + - codedata:/config + # mount docker socket to manage host docker + - /var/run/docker.sock:/var/run/docker.sock + # no need to expose the port. traefik acts as reverse proxy and handles the https access. + #ports: + # - 8443:8443 + networks: + - arkanum-sphere + - traefik-public + +volumes: + codedata: + +networks: + arkanum-sphere: + traefik-public: + external: true +``` + +> 💡 NOTE: For advanced config with additional environment variables see [linuxserver/docker-code-server](https://github.com/linuxserver/docker-code-server) help. +### 2.b Use Docker-Compose + +This is a basic example for a `docker-compose` file from the [linuxserver/docker-code-server](https://github.com/linuxserver/docker-code-server) project. + +See their [docs](https://github.com/linuxserver/docker-code-server#parameters) about a detailed help for advanced config parameters. + +```yaml +--- +version: "3.8" +services: + arkanum: + image: gitea.ocram85.com/codeserver/arkanum:1.0.0 + container_name: code-server + environment: + - PUID=1000 + - PGID=1000 + - TZ=Europe/London + - PASSWORD=password #optional + - HASHED_PASSWORD= #optional + - SUDO_PASSWORD=password #optional + - SUDO_PASSWORD_HASH= #optional + - PROXY_DOMAIN=code-server.my.domain #optional + - DEFAULT_WORKSPACE=/config/workspace #optional + volumes: + - /path/to/appdata/config:/config + ports: + - 8443:8443 + restart: unless-stopped +``` + +### 3. 🦶 First Steps + +After summon Arkanum your first steps should be to set your username and email in the git config: + +```bash +arkanum git setup "my-name" "my-email" +``` + +And that's it. Now you're ready use arkanum as your daily remote code editor. 😄 + +## 📖 Content + +

+ + Screenshot1 + +

diff --git a/docs/index.md b/docs/index.md index 9033e73..eb11ddb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,26 +11,23 @@ hero: alt: Arkanum actions: - theme: brand - text: Quick start - link: /markdown-examples + text: 🤖 Get Started + link: /guide/about - theme: alt - text: API Examples - link: /api-examples + text: View on Gitea + link: https://gitea.ocram85.com/CodeServer/arkanum features: - - title: Batteries Included - icon: 🔋 - details: Already contains best extensions and themes for quick start. - - title: Access anywhere + - title: Beginner Friendly + icon: ✨ + details: Already contains basic extensions and theme setup for quick start. + - title: Access Anywhere icon: 🌎 details: Access your dev environment from anywhere. - title: arkanum cli icon: 🧙 - details: Includes arkanum cli to install most wanted languages and frameworks. + details: Includes arkanum cli to install additional languages and frameworks. - title: Gitea + CI/CD icon: 🚧 - details: dfdf - - title: Base on trusted Sources - icon: 🏗️ - details: Arkanum is build on trusted projects like code-server and linuxserver.io + details: Optimized tooling for Gitea + Woodpecker-CI workflows. --- diff --git a/docs/markdown-examples.md b/docs/markdown-examples.md deleted file mode 100644 index 3ea9aa9..0000000 --- a/docs/markdown-examples.md +++ /dev/null @@ -1,85 +0,0 @@ -# Markdown Extension Examples - -This page demonstrates some of the built-in markdown extensions provided by VitePress. - -## Syntax Highlighting - -VitePress provides Syntax Highlighting powered by [Shikiji](https://github.com/antfu/shikiji), with additional features like line-highlighting: - -**Input** - -````md -```js{4} -export default { - data () { - return { - msg: 'Highlighted!' - } - } -} -``` -```` - -**Output** - -```js{4} -export default { - data () { - return { - msg: 'Highlighted!' - } - } -} -``` - -## Custom Containers - -**Input** - -```md -::: info -This is an info box. -::: - -::: tip -This is a tip. -::: - -::: warning -This is a warning. -::: - -::: danger -This is a dangerous warning. -::: - -::: details -This is a details block. -::: -``` - -**Output** - -::: info -This is an info box. -::: - -::: tip -This is a tip. -::: - -::: warning -This is a warning. -::: - -::: danger -This is a dangerous warning. -::: - -::: details -This is a details block. -::: - -## More - -Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown). diff --git a/docs/public/favicon2.png b/docs/public/faviconBg.png similarity index 100% rename from docs/public/favicon2.png rename to docs/public/faviconBg.png diff --git a/docs/public/logo2.png b/docs/public/logoBg.png similarity index 100% rename from docs/public/logo2.png rename to docs/public/logoBg.png