diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..513a0dc --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,47 @@ +name: Build / Deploy docs + +on: + push: + tags: + - 'v*' + workflow_dispatch: + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install JS dependencies + run: | + npm install vitepress@1.3.4 tailwindcss@3.4.10 + + - name: Build docs + run: | + cd docs + npx tailwindcss -i .vitepress/theme/style.css -o .vitepress/theme/theme.css -c .vitepress/tailwind.config.js + npm run docs:build + + - name: Deploy to server + uses: appleboy/scp-action@master + with: + host: ${{ secrets.SERVER_HOST }} + username: ${{ secrets.SERVER_USERNAME }} + key: ${{ secrets.SERVER_SSH_KEY }} + source: "docs/.vitepress/dist/*" + target: ${{ secrets.SERVER_PATH }} + + - name: Update remote docs + uses: appleboy/ssh-action@master + with: + host: ${{ secrets.SERVER_HOST }} + username: ${{ secrets.SERVER_USERNAME }} + key: ${{ secrets.SERVER_SSH_KEY }} + script: | + ${{ secrets.UPDATE_DOCS }} \ No newline at end of file diff --git a/.gitignore b/.gitignore index e96bcd2..762d863 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,5 @@ public/assets/* public/manifest.json opengist build/ +docs/.vitepress/dist/ +docs/.vitepress/cache/ diff --git a/README.md b/README.md index 70d4e1a..14d77dd 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Opengist -Opengist +Opengist Opengist is a **self-hosted** pastebin **powered by Git**. All snippets are stored in a Git repository and can be read and/or modified using standard Git commands, or with the web interface. It is similiar to [GitHub Gist](https://gist.github.com/), but open-source and could be self-hosted. -[Documentation](/docs) • [Discord](https://discord.gg/9Pm3X5scZT) • [Demo](https://demo.opengist.io) +[Home Page](https://opengist.io) • [Documentation](https://opengist.io/docs) • [Discord](https://discord.gg/9Pm3X5scZT) • [Demo](https://demo.opengist.io) ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/thomiceli/opengist?sort=semver) @@ -103,11 +103,11 @@ Opengist is now running on port 6157, you can browse http://localhost:6157 --- -To create and run a development environment, see [run-development.md](/docs/contributing/run-development.md). +To create and run a development environment, see [run-development.md](/docs/contributing/development.md). ## Documentation -The documentation is available in [/docs](/docs) directory. +The documentation is available at [https://opengist.io/](https://opengist.io/) or in the [/docs](/docs) directory. ## License diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 0000000..353abc4 --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,89 @@ +import {defineConfig} from 'vitepress' + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + title: "Opengist", + description: "Documention for Opengist", + rewrites: { + 'index.md': 'index.md', + 'introduction.md': 'docs/index.md', + ':path(.*)': 'docs/:path' + }, + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + logo: 'https://raw.githubusercontent.com/thomiceli/opengist/master/public/opengist.svg', + logoLink: '/', + nav: [ + { text: 'Demo', link: 'https://demo.opengist.io' }, + { text: 'Translate', link: 'https://tr.opengist.io' } + ], + + sidebar: { + '/docs/': [ + { + text: '', items: [ + {text: 'Introduction', link: '/docs'}, + {text: 'Installation', link: '/docs/installation', items: [ + {text: 'Docker', link: '/docs/installation/docker'}, + {text: 'Binary', link: '/docs/installation/binary'}, + {text: 'Source', link: '/docs/installation/source'}, + ], + collapsed: true + }, + {text: 'Update', link: '/docs/update'}, + ], collapsed: false + }, + { + text: 'Configuration', base: '/docs/configuration', items: [ + {text: 'Configure Opengist', link: '/configure'}, + {text: 'Admin panel', link: '/admin-panel'}, + {text: 'OAuth Providers', link: '/oauth-providers'}, + {text: 'Custom assets', link: '/custom-assets'}, + {text: 'Custom links', link: '/custom-links'}, + {text: 'Cheat Sheet', link: '/cheat-sheet'}, + ], collapsed: false + }, + { + text: 'Usage', base: '/docs/usage', items: [ + {text: 'Init via Git', link: '/init-via-git'}, + {text: 'Embed Gist', link: '/embed'}, + {text: 'Gist as JSON', link: '/gist-json'}, + {text: 'Import Gists from Github', link: '/import-from-github-gist'}, + {text: 'Git push options', link: '/git-push-options'}, + ], collapsed: false + }, + { + text: 'Administration', base: '/docs/administration', items: [ + {text: 'Run with systemd', link: '/run-with-systemd'}, + {text: 'Reverse proxy', items: [ + {text: 'Nginx', link: '/nginx-reverse-proxy'}, + {text: 'Traefik', link: '/traefik-reverse-proxy'}, + ], collapsed: true}, + {text: 'Fail2ban', link: '/fail2ban-setup'}, + {text: 'Healthcheck', link: '/healthcheck'}, + ], collapsed: false + }, + { + text: 'Contributing', base: '/docs/contributing', items: [ + {text: 'Community', link: '/community'}, + {text: 'Development', link: '/development'}, + ], collapsed: false + }, + + ]}, + + socialLinks: [ + {icon: 'github', link: 'https://github.com/thomiceli/opengist'} + ], + editLink: { + pattern: 'https://github.com/thomiceli/opengist/edit/stable/docs/:path' + }, + // @ts-ignore + lastUpdated: true, + + }, + head: [ + ['link', {rel: 'icon', href: '/favicon.svg'}], + ], + ignoreDeadLinks: true +}) diff --git a/docs/.vitepress/tailwind.config.js b/docs/.vitepress/tailwind.config.js new file mode 100644 index 0000000..53ceeb0 --- /dev/null +++ b/docs/.vitepress/tailwind.config.js @@ -0,0 +1,37 @@ +const colors = require('tailwindcss/colors') + +/** @type {import('tailwindcss').Config} */ +module.exports = { + content: [ + "./.vitepress/theme/*.vue", + ], + theme: { + colors: { + transparent: 'transparent', + current: 'currentColor', + white: colors.white, + black: colors.black, + gray: { + 50: "#EEEFF1", + 100: "#DEDFE3", + 200: "#BABCC5", + 300: "#999CA8", + 400: "#75798A", + 500: "#585B68", + 600: "#464853", + 700: "#363840", + 800: "#232429", + 900: "#131316" + }, + indigo: colors.indigo, + + }, + extend: { + borderWidth: { + '1': '1px', + } + }, + }, + plugins: [], + darkMode: 'class', +} diff --git a/docs/.vitepress/theme/Home.vue b/docs/.vitepress/theme/Home.vue new file mode 100644 index 0000000..72c85bd --- /dev/null +++ b/docs/.vitepress/theme/Home.vue @@ -0,0 +1,101 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue new file mode 100644 index 0000000..80e2694 --- /dev/null +++ b/docs/.vitepress/theme/Layout.vue @@ -0,0 +1,16 @@ + + + \ No newline at end of file diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts new file mode 100644 index 0000000..baf48b0 --- /dev/null +++ b/docs/.vitepress/theme/index.ts @@ -0,0 +1,12 @@ +import { h } from 'vue' +import type { Theme } from 'vitepress' +import DefaultTheme from 'vitepress/theme' +import Layout from "./Layout.vue"; + +export default { + ...DefaultTheme, + Layout, + enhanceApp({ app, router, siteData }) { + // ... + } +} satisfies Theme diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css new file mode 100644 index 0000000..462dc30 --- /dev/null +++ b/docs/.vitepress/theme/style.css @@ -0,0 +1,147 @@ +/** + * Customize default theme styling by overriding CSS variables: + * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css + */ + +/** + * Colors + * + * Each colors have exact same color scale system with 3 levels of solid + * colors with different brightness, and 1 soft color. + * + * - `XXX-1`: The most solid color used mainly for colored text. It must + * satisfy the contrast ratio against when used on top of `XXX-soft`. + * + * - `XXX-2`: The color used mainly for hover state of the button. + * + * - `XXX-3`: The color for solid background, such as bg color of the button. + * It must satisfy the contrast ratio with pure white (#ffffff) text on + * top of it. + * + * - `XXX-soft`: The color used for subtle background such as custom container + * or badges. It must satisfy the contrast ratio when putting `XXX-1` colors + * on top of it. + * + * The soft color must be semi transparent alpha channel. This is crucial + * because it allows adding multiple "soft" colors on top of each other + * to create a accent, such as when having inline code block inside + * custom containers. + * + * - `default`: The color used purely for subtle indication without any + * special meanings attched to it such as bg color for menu hover state. + * + * - `brand`: Used for primary brand colors, such as link text, button with + * brand theme, etc. + * + * - `tip`: Used to indicate useful information. The default theme uses the + * brand color for this by default. + * + * - `warning`: Used to indicate warning to the users. Used in custom + * container, badges, etc. + * + * - `danger`: Used to show error, or dangerous message to the users. Used + * in custom container, badges, etc. + * -------------------------------------------------------------------------- */ + + :root { + --vp-c-default-1: var(--vp-c-gray-1); + --vp-c-default-2: var(--vp-c-gray-2); + --vp-c-default-3: var(--vp-c-gray-3); + --vp-c-default-soft: var(--vp-c-gray-soft); + + --vp-c-brand-1: var(--vp-c-indigo-1); + --vp-c-brand-2: var(--vp-c-indigo-2); + --vp-c-brand-3: var(--vp-c-indigo-3); + --vp-c-brand-soft: var(--vp-c-indigo-soft); + + --vp-c-tip-1: var(--vp-c-brand-1); + --vp-c-tip-2: var(--vp-c-brand-2); + --vp-c-tip-3: var(--vp-c-brand-3); + --vp-c-tip-soft: var(--vp-c-brand-soft); + + --vp-c-warning-1: var(--vp-c-yellow-1); + --vp-c-warning-2: var(--vp-c-yellow-2); + --vp-c-warning-3: var(--vp-c-yellow-3); + --vp-c-warning-soft: var(--vp-c-yellow-soft); + + --vp-c-danger-1: var(--vp-c-red-1); + --vp-c-danger-2: var(--vp-c-red-2); + --vp-c-danger-3: var(--vp-c-red-3); + --vp-c-danger-soft: var(--vp-c-red-soft); +} + +/** + * Component: Button + * -------------------------------------------------------------------------- */ + +:root { + --vp-button-brand-border: transparent; + --vp-button-brand-text: var(--vp-c-white); + --vp-button-brand-bg: var(--vp-c-brand-3); + --vp-button-brand-hover-border: transparent; + --vp-button-brand-hover-text: var(--vp-c-white); + --vp-button-brand-hover-bg: var(--vp-c-brand-2); + --vp-button-brand-active-border: transparent; + --vp-button-brand-active-text: var(--vp-c-white); + --vp-button-brand-active-bg: var(--vp-c-brand-1); +} + +/** + * Component: Home + * -------------------------------------------------------------------------- */ + +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient( + 120deg, + #0f0513 30%, + #7e8b90 + ); + + --vp-home-hero-image-background-image: linear-gradient( + -45deg, + #bd34fe 50%, + #47caff 50% + ); + --vp-home-hero-image-filter: blur(44px); +} + +@media (min-width: 640px) { + :root { + --vp-home-hero-image-filter: blur(56px); + } +} + +@media (min-width: 960px) { + :root { + --vp-home-hero-image-filter: blur(68px); + } +} + +/** + * Component: Custom Block + * -------------------------------------------------------------------------- */ + +:root { + --vp-custom-block-tip-border: transparent; + --vp-custom-block-tip-text: var(--vp-c-text-1); + --vp-custom-block-tip-bg: var(--vp-c-brand-soft); + --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft); +} + +/** + * Component: Algolia + * -------------------------------------------------------------------------- */ + +.DocSearch { + --docsearch-primary-color: var(--vp-c-brand-1) !important; +} + +.content img { + padding-left: 20px; + height: 108px; +} + +@tailwind base; +@tailwind components; +@tailwind utilities; \ No newline at end of file diff --git a/docs/administration/traefik-reverse-proxy.md b/docs/administration/traefik-reverse-proxy.md new file mode 100644 index 0000000..592e3ff --- /dev/null +++ b/docs/administration/traefik-reverse-proxy.md @@ -0,0 +1,48 @@ +# Use Traefik as a reverse proxy + +You can set up Traefik in two ways: + +
+Using Docker labels + +Add these labels to your `docker-compose.yml` file: + +```yml +labels: + - traefik.http.routers.opengist.rule=Host(`opengist.example.com`) # Change to your subdomain + # Uncomment the line below if you run Opengist in a subdirectory + # - traefik.http.routers.app1.rule=PathPrefix(`/opengist{regex:$$|/.*}`) # Change opentist in the regex to yuor subdirectory name + - traefik.http.routers.opengist.entrypoints=websecure # Change to the name of your 443 port entrypoint + - traefik.http.routers.opengist.tls.certresolver=lets-encrypt # Change to certresolver's name + - traefik.http.routers.opengist.service=opengist + - traefik.http.services.opengist.loadBalancer.server.port=6157 +``` +
+
+Using a yml file + +> [!Note] +> Don't forget to change the `` to your server's IP + +`traefik_dynamic.yml` +```yml +http: + routers: + opengist: + entrypoints: websecure + rule: Host(`opengist.example.com`) # Comment this line and uncomment the line below if using a subpath + # rule: PathPrefix(`/opengist{regex:$$|/.*}`) # Change opentist in the regex to yuor subdirectory name + # middlewares: + # - opengist-fail2ban + service: opengist + tls: + certresolver: lets-encrypt + services: + opengist: + loadbalancer: + servers: + - url: "http://:6157" + +``` + +
\ No newline at end of file diff --git a/docs/configuration/admin-panel.md b/docs/configuration/admin-panel.md new file mode 100644 index 0000000..42a0731 --- /dev/null +++ b/docs/configuration/admin-panel.md @@ -0,0 +1,53 @@ +# Admin panel + +The first user created on your Opengist instance has access to the Admin panel. + +To access the Admin panel: + +1. Log in +2. Click your username in the upper right corner +3. Select `Admin` + +## Usage + +### General + +Here you can see some basic information, like Opengist version, alongside some stats. + +You can also start some actions like forcing synchronization of gists, +starting garbage collection, etc. + +### Users + +Here you can see your users and delete them. + +### Gists + +Here you can see all the gists and some basic information about them. You also have an option +to delete them. + + +### Invitations + +Here you can create invitation links with some options like limiting the number of signed up +users or setting an expiration date. + +> [!Note] +> Invitation links override the `Disable signup` option but not the `Disable login form` option. +> +> Users will see only the OAuth providers when `Disable login form` is enabled. + +### Configuration + +Here you can change a limited number of settings without restarting the instance. + +- Disable signup + - Forbid the creation of new accounts. +- Require login + - Enforce users to be logged in to see gists. +- Allow individual gists without login + - Allow individual gists to be viewed and downloaded without login, while requiring login for discovering gists. +- Disable login form + - Forbid logging in via the login form to force using OAuth providers instead. +- Disable Gravatar + - Disable the usage of Gravatar as an avatar provider. \ No newline at end of file diff --git a/docs/configuration/cheat-sheet.md b/docs/configuration/cheat-sheet.md index d182162..d8880a9 100644 --- a/docs/configuration/cheat-sheet.md +++ b/docs/configuration/cheat-sheet.md @@ -1,3 +1,7 @@ +--- +aside: false +--- + # Configuration Cheat Sheet | YAML Config Key | Environment Variable | Default value | Description | diff --git a/docs/configuration/index.md b/docs/configuration/configure.md similarity index 93% rename from docs/configuration/index.md rename to docs/configuration/configure.md index 3283e27..f3fb4f7 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/configure.md @@ -27,7 +27,7 @@ Usage via command line : ./opengist --config /path/to/config.yml ``` -You can start by copying and/or modifying the provided [config.yml](/config.yml) file. +You can start by copying and/or modifying the provided [config.yml](https://github.com/thomiceli/opengist/blob/stable/config.yml) file. ## Configuration via Environment Variables diff --git a/docs/configuration/custom-links.md b/docs/configuration/custom-links.md index d05035b..22af528 100644 --- a/docs/configuration/custom-links.md +++ b/docs/configuration/custom-links.md @@ -52,11 +52,11 @@ If you want your custom page to integrate well into the existing theme, you can

Sub-Heading

-

+

{{ template "footer" . }} ``` -You can adjust above as needed. Opengist uses Tailwind CSS classes. +You can adjust above as needed. Opengist uses TailwindCSS classes. diff --git a/docs/administration/oauth-providers.md b/docs/configuration/oauth-providers.md similarity index 67% rename from docs/administration/oauth-providers.md rename to docs/configuration/oauth-providers.md index 8a9fbac..b7cfe57 100644 --- a/docs/administration/oauth-providers.md +++ b/docs/configuration/oauth-providers.md @@ -2,51 +2,76 @@ Opengist can be configured to use OAuth to authenticate users, with GitHub, Gitea, or OpenID Connect. -## Github +## GitHub * Add a new OAuth app in your [GitHub account settings](https://github.com/settings/applications/new) * Set 'Authorization callback URL' to `http://opengist.url/oauth/github/callback` -* Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](/docs/configuration/cheat-sheet.md) : +* Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](cheat-sheet.md) : ```yaml github.client-key: github.secret: ``` + ```shell + OG_GITHUB_CLIENT_KEY= + OG_GITHUB_SECRET= + ``` ## GitLab * Add a new OAuth app in Application settings from the [GitLab instance](https://gitlab.com/-/user_settings/applications) * Set 'Redirect URI' to `http://opengist.url/oauth/gitlab/callback` -* Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](/docs/configuration/cheat-sheet.md) : +* Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](cheat-sheet.md) : ```yaml gitlab.client-key: gitlab.secret: # URL of the GitLab instance. Default: https://gitlab.com/ gitlab.url: https://gitlab.com/ ``` + ```shell + OG_GITLAB_CLIENT_KEY= + OG_GITLAB_SECRET= + # URL of the GitLab instance. Default: https://gitlab.com/ + OG_GITLAB_URL=https://gitlab.com/ + ``` + ## Gitea * Add a new OAuth app in Application settings from the [Gitea instance](https://gitea.com/user/settings/applications) * Set 'Redirect URI' to `http://opengist.url/oauth/gitea/callback` -* Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](/docs/configuration/cheat-sheet.md) : +* Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](cheat-sheet.md) : ```yaml gitea.client-key: gitea.secret: # URL of the Gitea instance. Default: https://gitea.com/ gitea.url: http://localhost:3000 ``` + ```shell + OG_GITEA_CLIENT_KEY= + OG_GITEA_SECRET= + # URL of the Gitea instance. Default: https://gitea.com/ + OG_GITEA_URL=http://localhost:3000 + ``` + ## OpenID Connect * Add a new OAuth app in Application settings of your OIDC provider * Set 'Redirect URI' to `http://opengist.url/oauth/openid-connect/callback` -* Copy the 'Client ID', 'Client Secret', and the discovery endpoint, and add them to the [configuration](/docs/configuration/cheat-sheet.md) : +* Copy the 'Client ID', 'Client Secret', and the discovery endpoint, and add them to the [configuration](cheat-sheet.md) : ```yaml oidc.client-key: oidc.secret: # Discovery endpoint of the OpenID provider. Generally something like http://auth.example.com/.well-known/openid-configuration oidc.discovery-url: http://auth.example.com/.well-known/openid-configuration ``` + ```shell + OG_OIDC_CLIENT_KEY= + OG_OIDC_SECRET= + # Discovery endpoint of the OpenID provider. Generally something like http://auth.example.com/.well-known/openid-configuration + OG_OIDC_DISCOVERY_URL=http://auth.example.com/.well-known/openid-configuration + ``` + \ No newline at end of file diff --git a/docs/contributing/community.md b/docs/contributing/community.md new file mode 100644 index 0000000..b9d1771 --- /dev/null +++ b/docs/contributing/community.md @@ -0,0 +1,6 @@ +# Community + +The following is a list of resources made by happy users of Opengist. Feel free to make a PR add your own! + +- [Aetherinox/opengist-debian](https://github.com/Aetherinox/opengist-debian) - A Debian package for Opengist +- [How to Install Opengist on Your Synology NAS](https://mariushosting.com/how-to-install-opengist-on-your-synology-nas/) - A guide to install Opengist on a Synology NAS diff --git a/docs/contributing/run-development.md b/docs/contributing/development.md similarity index 100% rename from docs/contributing/run-development.md rename to docs/contributing/development.md diff --git a/docs/index.md b/docs/index.md index 8e583ae..5f3a6d3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,54 +1,4 @@ -# Opengist - -Opengist is a **self-hosted** pastebin **powered by Git**. All snippets are stored in a Git repository and can be -read and/or modified using standard Git commands, or with the web interface. -It is similiar to [GitHub Gist](https://gist.github.com/), but open-source and could be self-hosted. - -Written in [Go](https://go.dev), Opengist aims to be fast and easy to deploy. - - -## Features - -* Create public, unlisted or private snippets -* [Init](/docs/usage/init-via-git.md) / Clone / Pull / Push snippets **via Git** over HTTP or SSH -* Syntax highlighting ; markdown & CSV support -* Search code in snippets ; browse users snippets, likes and forks -* Embed snippets in other websites -* Revisions history -* Like / Fork snippets -* Editor with indentation mode & size ; drag and drop files -* Download raw files or as a ZIP archive -* Retrieve snippet data/metadata via a JSON API -* OAuth2 login with GitHub, GitLab, Gitea, and OpenID Connect -* Avatars via Gravatar or OAuth2 providers -* Light/Dark mode -* Responsive UI -* Enable or disable signups -* Restrict or unrestrict snippets visibility to anonymous users -* Admin panel : - * delete users/gists; - * clean database/filesystem by syncing gists - * run `git gc` for all repositories -* SQLite database -* Logging -* Docker support - - -## System requirements - -[Git](https://git-scm.com/download) is obviously required to run Opengist, as it's the main feature of the app. -Version **2.28** or later is recommended as the app has not been tested with older Git versions and some features would not work. - -[OpenSSH](https://www.openssh.com/) suite if you wish to use Git over SSH. - - -## Components - -* Backend Web Framework: [Echo](https://echo.labstack.com/) -* ORM: [GORM](https://gorm.io/) -* Frontend libraries: - * [Tailwind CSS](https://tailwindcss.com/) - * [CodeMirror](https://codemirror.net/) - * [Day.js](https://day.js.org/) - * [highlight.js](https://highlightjs.org/) - * and [others](/package.json) +--- +layout: home +navbar: false +--- diff --git a/docs/installation.md b/docs/installation.md index 4746a9b..dbb7a50 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,74 +1,7 @@ -# Installation +# Install Opengist -## With Docker +There are several ways to install Opengist, depending on your preferences and your environment. -Docker [images](https://github.com/thomiceli/opengist/pkgs/container/opengist) are available for each release : - -```shell -docker pull ghcr.io/thomiceli/opengist:1 -``` - -It can be used in a `docker-compose.yml` file : - -1. Create a `docker-compose.yml` file with the following content -2. Run `docker compose up -d` -3. Opengist is now running on port 6157, you can browse http://localhost:6157 - -```yml -version: "3" - -services: - opengist: - image: ghcr.io/thomiceli/opengist:1 - container_name: opengist - restart: unless-stopped - ports: - - "6157:6157" # HTTP port - - "2222:2222" # SSH port, can be removed if you don't use SSH - volumes: - - "$HOME/.opengist:/opengist" -``` - -You can define which user/group should run the container and own the files by setting the `UID` and `GID` environment -variables : - -```yml -services: - opengist: - # ... - environment: - UID: 1001 - GID: 1001 -``` - -## Via binary - -Download the archive for your system from the release page [here](https://github.com/thomiceli/opengist/releases/latest), and extract it. - -```shell -# example for linux amd64 -wget https://github.com/thomiceli/opengist/releases/download/v1.7.4/opengist1.7.4-linux-amd64.tar.gz - -tar xzvf opengist1.7.4-linux-amd64.tar.gz -cd opengist -chmod +x opengist -./opengist # with or without `--config config.yml` -``` - - -## From source - -Requirements: -* [Git](https://git-scm.com/downloads) (2.28+) -* [Go](https://go.dev/doc/install) (1.22+) -* [Node.js](https://nodejs.org/en/download/) (16+) -* [Make](https://linux.die.net/man/1/make) (optional, but easier) - -```shell -git clone https://github.com/thomiceli/opengist -cd opengist -make -./opengist -``` - -Opengist is now running on port 6157, you can browse http://localhost:6157 +- [Docker](installation/docker.md) +- [Source](installation/source.md) +- [Binary](installation/binary.md) diff --git a/docs/installation/binary.md b/docs/installation/binary.md new file mode 100644 index 0000000..49006d5 --- /dev/null +++ b/docs/installation/binary.md @@ -0,0 +1,14 @@ +# Install from binary + +Download the archive for your system from the release page [here](https://github.com/thomiceli/opengist/releases/latest), and extract it. + +```shell +# example for linux amd64 +wget https://github.com/thomiceli/opengist/releases/download/v1.7.4/opengist1.7.4-linux-amd64.tar.gz + +tar xzvf opengist1.7.4-linux-amd64.tar.gz +cd opengist +chmod +x opengist +./opengist # with or without `--config config.yml` +``` + diff --git a/docs/installation/docker.md b/docs/installation/docker.md new file mode 100644 index 0000000..a1f0fcd --- /dev/null +++ b/docs/installation/docker.md @@ -0,0 +1,43 @@ +# Install with Docker + +Docker [images](https://github.com/thomiceli/opengist/pkgs/container/opengist) are available for each release : + +```shell +docker pull ghcr.io/thomiceli/opengist:1 +``` + +It can be used in a `docker-compose.yml` file : + +1. Create a `docker-compose.yml` file with the following content +2. Run `docker compose up -d` +3. Opengist is now running on port 6157, you can browse http://localhost:6157 + +```yml +version: "3" + +services: + opengist: + image: ghcr.io/thomiceli/opengist:1 + container_name: opengist + restart: unless-stopped + ports: + - "6157:6157" # HTTP port + - "2222:2222" # SSH port, can be removed if you don't use SSH + volumes: + - "$HOME/.opengist:/opengist" + environment: + # OG_LOG_LEVEL: info + # other configuration options +``` + +You can define which user/group should run the container and own the files by setting the `UID` and `GID` environment +variables : + +```yml +services: + opengist: + # ... + environment: + UID: 1001 + GID: 1001 +``` diff --git a/docs/installation/source.md b/docs/installation/source.md new file mode 100644 index 0000000..4bc8bea --- /dev/null +++ b/docs/installation/source.md @@ -0,0 +1,19 @@ +# Installation from source + +Requirements: +* [Git](https://git-scm.com/downloads) (2.28+) +* [Go](https://go.dev/doc/install) (1.22+) +* [Node.js](https://nodejs.org/en/download/) (16+) +* [Make](https://linux.die.net/man/1/make) (optional, but easier) + +```shell +git clone https://github.com/thomiceli/opengist +cd opengist + +git checkout v1.7.4 # optional, to checkout the latest release + +make +./opengist +``` + +Opengist is now running on port 6157, you can browse http://localhost:6157 diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..0bf7814 --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,55 @@ +# Opengist + +Opengist + +Opengist is a **self-hosted** pastebin **powered by Git**. All snippets are stored in a Git repository and can be +read and/or modified using standard Git commands, or with the web interface. +It is similiar to [GitHub Gist](https://gist.github.com/), but open-source and could be self-hosted. + +Written in [Go](https://go.dev), Opengist aims to be fast and easy to deploy. + + +## Features + +* Create public, unlisted or private snippets +* [Init](usage/init-via-git.md) / Clone / Pull / Push snippets **via Git** over HTTP or SSH +* Syntax highlighting ; markdown & CSV support +* Search code in snippets ; browse users snippets, likes and forks +* Embed snippets in other websites +* Revisions history +* Like / Fork snippets +* Editor with indentation mode & size ; drag and drop files +* Download raw files or as a ZIP archive +* Retrieve snippet data/metadata via a JSON API +* OAuth2 login with GitHub, GitLab, Gitea, and OpenID Connect +* Avatars via Gravatar or OAuth2 providers +* Light/Dark mode +* Responsive UI +* Enable or disable signups +* Restrict or unrestrict snippets visibility to anonymous users +* Admin panel : + * delete users/gists; + * clean database/filesystem by syncing gists + * run `git gc` for all repositories +* SQLite database +* Logging +* Docker support + + +## System requirements + +[Git](https://git-scm.com/download) is obviously required to run Opengist, as it's the main feature of the app. +Version **2.28** or later is recommended as the app has not been tested with older Git versions and some features would not work. + +[OpenSSH](https://www.openssh.com/) suite if you wish to use Git over SSH. + + +## Components + +* Backend Web Framework: [Echo](https://echo.labstack.com/) +* ORM: [GORM](https://gorm.io/) +* Frontend libraries: + * [TailwindCSS](https://tailwindcss.com/) + * [CodeMirror](https://codemirror.net/) + * [Day.js](https://day.js.org/) + * and [others](/package.json) diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg new file mode 100644 index 0000000..f47dd16 --- /dev/null +++ b/docs/public/favicon.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/public/opengist-demo.png b/docs/public/opengist-demo.png new file mode 100644 index 0000000..0ffcfde Binary files /dev/null and b/docs/public/opengist-demo.png differ diff --git a/docs/update.md b/docs/update.md index c12625e..a448e97 100644 --- a/docs/update.md +++ b/docs/update.md @@ -1,4 +1,4 @@ -# Update +# Update Opengist ## Make a backup @@ -40,6 +40,7 @@ chmod +x opengist Stop the running instance; then pull the last changes from the master branch, and build the new version. ```shell +git switch master git pull make ./opengist diff --git a/docs/usage/init-via-git.md b/docs/usage/init-via-git.md index 231e698..3725896 100644 --- a/docs/usage/init-via-git.md +++ b/docs/usage/init-via-git.md @@ -39,4 +39,4 @@ To http://localhost:6157/init * [new branch] master -> master ``` -https://github.com/thomiceli/opengist/assets/27960254/3fe1a0ba-b638-4928-83a1-f38e46fea066 +