https://github.com/ctfer-io/ctfd-setup
Utility to version your CTFd setup configuration.
https://github.com/ctfer-io/ctfd-setup
action ctfd docker golang utility versionning
Last synced: 4 months ago
JSON representation
Utility to version your CTFd setup configuration.
- Host: GitHub
- URL: https://github.com/ctfer-io/ctfd-setup
- Owner: ctfer-io
- License: apache-2.0
- Created: 2024-04-07T20:10:30.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-07T19:09:39.000Z (11 months ago)
- Last Synced: 2025-07-07T20:56:24.328Z (11 months ago)
- Topics: action, ctfd, docker, golang, utility, versionning
- Language: Go
- Homepage:
- Size: 996 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
CTFd-Setup
Version your CTFd setup configuration.
CTFd does not have the concept of **configuration file**, leading to **deployment complications** and the **impossibility to version configurations**.
This is problematic for reproducibility or sharing configuration for debugging or replicating a CTF infrastructure.
Moreover, the setup API does not exist, so we had to map it to what the frontend calls in [go-ctfd](https://github.com/ctfer-io/go-ctfd/blob/main/api/setup.go).
To fill those gaps, we built `ctfd-setup` on top of the CTFd API. This utility helps setup a CTFd instance from a YAML configuration file, CLI flags and environment variables.
Thanks to this, you can integrate it using **GitHub Actions**, **Drone CI** or even as part of your **IaC provisionning**.
With `ctfd-setup` you can **setup your CTFd in a second**.
## How to use
### YAML
You can use `ctfd-setup` as a CLI tool and provision it a YAML configuration file.
```yaml
appearance:
name: 'My CTF'
description: 'My CTF description'
admin:
name: 'admin'
email: 'admin@super.ctf'
password: 'admin_password'
mode: users
```
**We encourage you to version this file** such that re-deployment is easy (e.g., for test purposes, or in case of a catastrophic failure of the infra during the event).
Nevertheless, please do not commit the admin credentials ! Use `from_env` objects instead (refer to [the YAML Schema](#schema) for more info) or use [CLI overrides](examples/cli-override/).
It could also deploy custom pages (like the index) as follows.
This feature is not available in CLI, [GitHub Actions](#github-actions) and [Drone CI](#drone-ci).
```yaml
# ... other configuration attributes
pages:
additional:
- title: CTFer.io example index
route: index
format: markdown
content: |
Some index page content
```
For further configuration, please refer to the binary's specific API through `ctfd-setup --help`.
### GitHub Actions
To improve our own workflows and share knownledges and tooling, we built a GitHub Action: `ctfer-io/ctfd-setup`.
You can use it given the following example.
```yaml
name: 'My workflow'
on:
push:
branches:
- 'main'
jobs:
my-job:
runs-on: 'ubuntu-latest'
steps:
- name: 'Setup CTFd'
uses: 'ctfer-io/ctfd-setup@v1.8.1'
with:
url: ${{ secrets.CTFD_URL }}
file: '.ctfd.yaml'
# or directly attributes
appearance_name: 'My CTF'
appearance_description: 'My CTF description'
admin_name: ${{ secrets.ADMIN_USERNAME }}
admin_email: ${{ secrets.ADMIN_EMAIL }}
admin_password: ${{ secrets.ADMIN_PASSWORD }}
# ... and so on (non-mandatory attributes)
```
### Drone CI
This could also be used as part of a Drone CI use `ctferio/ctfd-setup`.
```yaml
kind: pipeline
type: docker
name: 'My pipeline'
trigger:
branch:
- main
event:
- push
steps:
# ...
- name: 'Setup CTFd'
image: 'ctferio/ctfd-setup@v1.8.1'
settings:
url:
from_secret: CTFD_URL
file: '.ctfd.yaml'
# or directly attributes
appearance_name: 'My CTF'
appearance_description: 'My CTF description'
admin_name:
from_secret: ADMIN_USERNAME
admin_email:
from_secret: ADMIN_EMAIL
admin_password:
from_secret: ADMIN_PASSWORD
# ... and so on (non-mandatory attributes)
```
## Schema
For ease of use, you can generate and use the YAML schema using `ctfd-setup schema`.
### In file
**(Optional)** In your `.ctfd.yaml` file you could then prepend `# yaml-language-server: $schema=file:///path/to/schema.json`.
> [!NOTE]
> This will appear by default if your IDE has a YAML extension with support of the [JSON SchemaStore](https://www.schemastore.org/json/).
### In VSCode
In case you are working in an air-gapped environment or working on improving the project, you may want your schema to automatically target your configuration files.
To do so, add the following to your `.vscode/settings.json`.
```json
{
"yaml.schemas": {
"schema.json": ".ctfd.yaml"
}
}
```