{"id":20658069,"url":"https://github.com/deepfence/documentationwebsite","last_synced_at":"2025-04-19T13:19:11.716Z","repository":{"id":49844784,"uuid":"517673619","full_name":"deepfence/DocumentationWebsite","owner":"deepfence","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-16T12:06:23.000Z","size":2887,"stargazers_count":35,"open_issues_count":10,"forks_count":3,"subscribers_count":5,"default_branch":"release-2.5","last_synced_at":"2025-04-16T17:25:00.839Z","etag":null,"topics":["documentation","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deepfence.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-25T13:20:21.000Z","updated_at":"2025-04-16T12:06:27.000Z","dependencies_parsed_at":"2023-02-17T22:01:26.501Z","dependency_job_id":"aa1dd67f-6154-4407-ac0c-24060be6f36c","html_url":"https://github.com/deepfence/DocumentationWebsite","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepfence%2FDocumentationWebsite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepfence%2FDocumentationWebsite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepfence%2FDocumentationWebsite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepfence%2FDocumentationWebsite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deepfence","download_url":"https://codeload.github.com/deepfence/DocumentationWebsite/tar.gz/refs/heads/release-2.5","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249702807,"owners_count":21312761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","hacktoberfest"],"created_at":"2024-11-16T18:24:38.772Z","updated_at":"2025-04-19T13:19:11.682Z","avatar_url":"https://github.com/deepfence.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Deepfence Community and Documentation Website\n\nThis website serves two purposes:\n\n * As a product showcase and starting point for community users to find useful resources\n * To host documentation for the individual open source and enterprise products\n\nThe build process imports the documentation from individual Deepfence projects to create a larger website that documents all projects in one place.\n\nTo prepare a project for documentation, jump forward to the section [Adding docs to your own project](#adding-docs-to-your-own-project).\n\nThe website is built using [Docusaurus 2](https://docusaurus.io/).\n\n## Quick Start\n\nClone the repo, then:\n\n### Initialize the components:\n\nImport the product docs from each project as a submodule.  Do this once:\n\n```bash\ngit submodule init\n```\n\nInitialize the dependencies.  Do this once:\n\n```bash\ncd docs\nyarn\n```\n\n### Import the docs content\n\nRun `make` to import the docs from the submodule projects.  Do this any time the docs are updated.\n\n```bash\ncd docs\nmake\n```\n\nThis operation will build the full source for the website:\n\n1. Refresh the remote projects (`git submodule update --remote`)\n1. Copy the docs content from each project (`docs/docs/projectname`) into the `docs/docs/projectname` location for this website, making some SEO customizations to the markdown frontmatter\n1. Copy the sidebar navigation from each project\n\n\n### Run the website\n\nRun `make run` to preview the website.\n\n```bash\nmake run\n```\n\nThis command (running [`docusaurus start`](https://docusaurus.io/docs/cli#docusaurus-start-sitedir)) builds a site preview, starts a local development server and opens up a browser window.  Most changes are reflected live without having to restart the server.  Use `--port` to select a different port to the default (:3000).\n\n### Build the content for publication\n\nRun `make build` to create the static, production-ready site.\n\n```bash\nmake build\n```\n\nA [full build](https://docusaurus.io/docs/cli#docusaurus-build-sitedir) goes through additional steps of packing, minifying and checking the build. This process may identify problems (e.g. broken links) that the quick preview build fails to detect.  It also enables the production-only features, such as google analytics and bigpicture beacons.\n\nThe resulting static build is located in `build/`.\n\nAlternatively, you can build-and-serve the site as follows:\n\n```bash\nyarn run serve --build --port 8000 --host 0.0.0.0\n```\n\n## Docker image\n\n```bash\n./bootstrap.sh\nmake\ndocker run -dit --restart=always --name=deepfence-docs -e GITHUB_USER=aaa -e GITHUB_ACCESS_TOKEN=aaa -p 80:80 quay.io/deepfenceio/deepfence_docs:latest\n```\n\n## Hosting the site\n\nThe site is intended to be hosted behind two domains:\n\n * `community.mydomain.com`: the primary domain to be used to serve the site\n * `docs.mydomain.com`: used to provide links to the docs, particularly for the enterprise product documentation where a 'community' domain would not be appropriate.\n\nIt's an antipattern to serve an SPA from multiple domains, and switch domains during routing. Configuration is non-trivial and the user experience is poor as a change of domain means a full reload of the SPA. Therefore, `docs.mydomain.com/productname` redirects to `community.mydomain.com/docs/productname` to achieve this.\n\nThe following, minimal NGINX configuration is sufficient:\n\n```nginx\n# File: conf.d/community.mydomain.com.conf\nserver {\n    server_name community.mydomain.com;\n    listen 80;\n\n    location / {\n        # the contents of the build process from Docusaurus\n        root /var/website/build;\n    }\n}\n```\n\n```nginx\n# File: conf.d/docs.mydomain.com.conf\nserver {\n    server_name docs.mydomain.com;\n    listen 80;\n\n    location / {\n        return 302 $scheme://community.mydomain.com/docs$request_uri;\n    }\n}\n```\n\nTLS certificates can be obtained using, for example, `certbot --nginx -d community.mydomain.com -d docs.mydomain.com`.\n\n\n## Editing the website\n\n### Editing the home page\n\nThe home page is located in `docs/src/pages/index.js`.  You can edit this page directly, and changes will be reflected immediately in the running website.\n\n### Editing the product docs\n\nThe product docs are sourced from the individual product repos, and are additionally decorated when they are imported (`make`) into the documentation website.  \n\nYou can edit the product docs in their respective submodules (`/product-docs`) and run `make` to re-import them.  Changes in the submodule are independent of this repo, can be submitted to their respective repos in the usual way.\n\nFor large changes to product docs (e.g. to prepare for a new release), it is better to develop these changes in the product's repo, test them locally, and then merge them to the product's `main` branch once complete.  You can then rebuild the documentation website.\n\n\n## Adding docs to your own project\n\nFollow these steps if you'd like to add docs to a new Deepfence project, and to have them included in this Documentation Website.\n\n### Get the Skeleton Files\n\nCheck out the GitHub repo you wish to add docs to.\n\nRemove (back-up) any existing `/docs/` directory in the repo.\n\nCopy `skel/docs` into the root of the repo, to create a new `/docs/` directory.  This directory contains:\n\n| Filename                                                                                                             | Purpose                                                       |\n|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|\n| `docs/docusaurus.config.js`                                                                                          | Sample configuration for your docusaurus docs site            |\n| `docs/sidebars.js`                                                                                                   | Sample sidebar for your documentation tree                    |\n| `docs/README.md`                                                                                                     | README for the docs in your new repo, with build instructions |\n| `docs/docs/threatmapper`                                                                                             | Location for your docs files (must rename first)              |\n| `docs/docs/threatmapper/index.md`                                                                                    | Your first documentation file                                 |\n| In `docs/static:`\u003cbr/\u003e `css/deepfence.css`,\u003cbr/\u003e `img/deepfence-logo-black.svg`,\u003cbr/\u003e `img/deepfence-logo-white.svg` | Styling for the deepfence skin for the `classic` theme        |\n| `docs/src/pages/index.md`                                                                                            | Default home page for Deepfence docs; no need to edit         |\n| `docs/yarn.lock`, `docs/package.json`                                                                                | NPM package list, used when initialized with `yarn`           |\n| `docs/.gitignore`                                                                                                    | Configuration to ignore node dependencies and temporary files |\n| `docs/babel.config.js`                                                                                               | Babel config                                                  |\n\nThese are the basic skeleton files needed to create a local docs site.\n\n### Customise the Skeleton files\n\nThe skeleton files are set up for the `threatmapper` product.  You'll need to select an alternative product name (e.g. `packetstreamer`) and edit the files appropriately.\n\n```bash\ncd docs\n```\n\nRename the `docs/threatmapper` directory to be product-appropriate, e.g. `packetstreamer`.  The markdown files for the product documentation will be wholy contained in that location.\n\nEdit `docusaurus.config.js` to make it product-appropriate.  You'll want to replace:\n\n1. config.title\n2. config.tagline\n3. config.presets.docs.editURL\n4. themeconfig.navbar.items[0]\n\nEdit `sidebars.js`:\n\n1. Replace the name of the sidebar object to the appropriate product name.  \n2. Correct the value in the `sidebar-title`\n\nYou will want to edit sidebars.js further, to define the nav structure of the documentation, but that can wait.\n\nCheck you've replaced all instances:\n\n```bash\n# Should return nothing\ngrep -ir threatmapper .\n```\n\nYou'll then want to add these files into your repository, before you initialize docusaurus:\n\n```bash\ngit add -A\n```\n\n### Initialise Docusaurus\n\nInitialize Docusaurus:\n\n```bash\ncd docs\n\n# you're now in the docs folder, with package.json and yarn.lock\n\n# Do this once to initialize the necessary packages\nyarn\n```\n\nDocusaurus will create a number of local temporary files which should not be tracked by git; these are excluded by the local `.gitignore`.\n\n### Start the docs application\n\n```bash\nyarn start\n```\n\n### Write your docs\n\n```bash\ncd docs\n```\n\nYou can now begin adding docs to your repo, into `docs/docs/productname`, and edit the sidebar at `docs/sidebar.js`. Take a look at other Deepfence products to understand the sidebar schema.\n\n## Adding a new project to the Documentation Website\n\nThis documentation website collects documentation from the various Deepfence projects (your `~repo/docs/docs/` folders) and imports the sidebar navigation from each project.  It assembles this into a single, larger Docusaurus project.\n\nYou'll need to:\n * Add your project as a new git submodule (`cd product-docs ; git submodule add \u003crepo.git\u003e`)\n * Add your project to the [MakeFile](docs/Makefile) targets so its assets are imported\n * Edit the site configuration [docusaurus.config.js](docs/docusaurus.config.js) to add your project into the nav, footer, editURL calculation and site metadata\n * Add your project to the sidebar generator [sidebars.js](docs/sidebars.js)\n\nAdditionally, you will want to:\n * Add an [icon](docs/static/img/products/) (source: [icons.svg](docs/static/img/products/icons.svg)) and [social card](docs/static/img/social) for your project\n * Edit the importer [import.pl](docs/import.pl) to decorate your docs with project-specific site metadata\n * Edit the home page [index.js](docs/src/pages/index.js) to add your project to the Community Home Page\n * Edit the documentation page [docs/index.md](docs/docs/index.md) to add your project to the documentation page\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepfence%2Fdocumentationwebsite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepfence%2Fdocumentationwebsite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepfence%2Fdocumentationwebsite/lists"}