#Quick Start

GZCTF is distributed as a Docker image, you can deploy a fully functional CTF platform with docker-compose. Please note that this is not the only way to deploy GZCTF, we recommend using Kubernetes to deploy. Please refer to for related deployment methods.

#Installation and configuration

1. To prepare for the following configuration, please prepare the following initialization parameters:

   • GZCTF_ADMIN_PASSWORD: Initial administrator password, effective when the database is not initialized, needs to be set at the first startup. It should be configured in compose.yml.
   • POSTGRES_PASSWORD: Database password, needs to be configured in compose.yml and appsettings.json.
   • XOR_KEY: A random string used to encrypt the competition private key, needs to be configured in appsettings.json.
   • PUBLIC_ENTRY: External access address, can be IP or domain name, needs to be configured in appsettings.json, used to provide the address of the problem container for players to access.

2. Save the following content as the appsettings.json file, and fill with your initialization parameters, please refer to appsettings.json configuration for detailed configuration instructions.

   {
     "AllowedHosts": "*",
     "ConnectionStrings": {
       "Database": "Host=db:5432;Database=gzctf;Username=postgres;Password=<Your POSTGRES_PASSWORD>"
     },
     "EmailConfig": {
       "SenderAddress": "",
       "SenderName": "",
       "UserName": "",
       "Password": "",
       "Smtp": {
         "Host": "localhost",
         "Port": 587
       }
     },
     "XorKey": "<Your XOR_KEY>",
     "ContainerProvider": {
       "Type": "Docker", // or "Kubernetes"
       "PortMappingType": "Default", // or "PlatformProxy"
       "EnableTrafficCapture": false,
       "PublicEntry": "<Your PUBLIC_ENTRY>", // or "xxx.xxx.xxx.xxx"
       // optional
       "DockerConfig": {
         "Uri": "unix:///var/run/docker.sock"
       }
     },
     "CaptchaConfig": {
       "Provider": "None", // or "CloudflareTurnstile" or "HashPow"
       "SiteKey": "<Your SITE_KEY>",
       "SecretKey": "<Your SECRET_KEY>"
     },
     "ForwardedOptions": {
       "ForwardedHeaders": 7,
       "ForwardLimit": 1,
       "KnownIPNetworks": ["192.168.12.0/8"]
     }
   }

3. Save the following content as the compose.yml file, and replace with your initialization parameters. Available backend languages are en-US, zh-CN, zh-TW, ja-JP, id-ID, ko-KR, ru-RU, de-DE, fr-FR, es-ES, vi-VN.

   services:
     gzctf:
       image: gztime/gzctf:latest
       restart: always
       environment:
         - "GZCTF_ADMIN_PASSWORD=<Your GZCTF_ADMIN_PASSWORD>"
         # choose your backend language `en_US` / `zh_CN` / `ja_JP` ...
         - "LC_ALL=en_US.UTF-8"
       ports:
         - "80:8080"
       volumes:
         - "./data/files:/app/files"
         - "./appsettings.json:/app/appsettings.json:ro"
         # - "./kube-config.yaml:/app/kube-config.yaml:ro" # this is required for k8s deployment
         - "/var/run/docker.sock:/var/run/docker.sock" # this is required for docker deployment
       depends_on:
         - db
   
     db:
       image: postgres:alpine
       restart: always
       environment:
         - "POSTGRES_PASSWORD=<Your POSTGRES_PASSWORD>"
       volumes:
         - "./data/db:/var/lib/postgresql"

networks:
  default:
    driver: bridge
    ipam:
      config:
        - subnet: 192.168.12.0/24

4. Run docker compose up -d to start GZCTF, then you can access GZCTF through the browser.

#Initial administrator

Production environment does not have administrative users by default, you need to set the initial administrator password when starting for the first time by setting the GZCTF_ADMIN_PASSWORD environment variable, and log in through the Admin account.

You can also manually change the database entry to set a currently registered user as an administrator. After the administrator registration is completed and successfully logged in, enter the selected database table and execute:

UPDATE "AspNetUsers" SET "Role"=3 WHERE "UserName"='your_admin_user_name';

You may need the following commands:

docker compose exec db psql -U postgres

psql (15.2)
Type "help" for help.

postgres=# \c gzctf
You are now connected to database "gzctf" as user "postgres".
gzctf=# #do your sql query

#Use Garnet/Redis as cache

If you want to use Garnet/Redis as a cache to get a more seamless version switching and server restart experience, you can add the following content to the above configuration:

1. compose.yml file

   services:
     gzctf:
       # ...
       depends_on:
         - db
         - cache
   
     cache:
       # It is recommended to use garnet, you can also use redis:alpine
       image: ghcr.io/microsoft/garnet-alpine:latest
       command: ["--bind", "0.0.0.0"]
       restart: always
   
     db:
       # ...

2. appsettings.json file

   {
     "AllowedHosts": "*",
     "ConnectionStrings": {
       // ...
       "RedisCache": "cache:6379,abortConnect=false"
     }
     // ...
   }

Then restart GZCTF with docker compose up -d.

#Container image

GZCTF has been pre-built and packaged as a unified Docker image, you can find the relevant image on Docker Hub.

Please use the following two container registries to get the image:

gztime/gzctf:latest
ghcr.io/gztimewalker/gzctf/gzctf:latest

Please use the develop image tag for test and development versions.

#Challenges configuration

Challenges configuration and examples can be found in the GZCTF-Challenges repository.

You can also refer to and learn from the public challenges repository of W4terCTF 2023. The challenges in this repository try to ensure that the Docker Image is small enough to be quickly deployed during the competition while keeping the challenges working properly.

It is recommended to use the GZCTF Challenge Base image as the base image for your challenge containers. We have minimized these base images as much as possible and update them regularly; using them can ensure that your challenge containers share image layers to the greatest extent possible, reducing storage space usage and image pull times.

GZCTF distributes dynamic flags by injecting the GZCTF_FLAG environment variable into the container, so please make sure that the text in this environment variable is placed in the appropriate location in the container initialization script of the challenge. Please note that this environment variable is initialized when the container is started, not when the container image is built.