Quick Start

This guide gets you from zero to a working private package repository in about 5 minutes. You will start the server with Docker, create your owner account through the web setup wizard, publish a package, and use it in another project.

Prerequisites

• Docker and Docker Compose installed
• Dart SDK installed (for publishing and using packages)

Start club

1. Clone the repository and enter the Docker directory

   git clone https://github.com/BirjuVachhani/club.git
   cd club/docker

2. Create the environment file

   cp .env.example .env

   Edit .env and set the required values:

   # Generate a secure JWT secret (must be at least 32 characters)
   JWT_SECRET=$(openssl rand -hex 32)
   
   cat > .env << EOF
   SERVER_URL=http://localhost:8080
   JWT_SECRET=$JWT_SECRET
   EOF

   Caution

   This uses http://localhost:8080 for local testing. For production, you must use an HTTPS URL. See the TLS guide for setup instructions.

3. Start the server

   docker compose up -d

   Wait a few seconds for the container to start, then verify:

   curl http://localhost:8080/api/v1/health

   You should see:

   {"status":"ok"}

4. Grab the one-time setup code from the logs

   On first startup, club prints a one-time setup code to the server logs. Find it with:

   docker compose logs club | grep -i "setup code"

   Copy this code. You will use it in the next step.

Create the owner account

club ships without any users. The first account is created through a one-shot web setup wizard, which is disabled automatically once it completes.

1. Open the setup page

   Navigate to http://localhost:8080/setup in your browser.

2. Verify the setup code

   Enter your email address and the one-time setup code from the logs, then submit. Verification is IP-pinned — only the same browser/IP can complete the second step.

3. Create your owner account

   Fill in your display name and password (and confirm the password), then submit. The first user is created with the owner role.

Note

Once setup completes, the /setup endpoints return 404 forever. Subsequent users are either invited by an owner/admin via the web UI or — if SIGNUP_ENABLED=true — can self-register as member accounts.

Login with the CLI

1. Install the club CLI

   curl -fsSL https://club.birju.dev/install.sh | bash

   Installs club to ~/.local/bin. Windows and manual-download options are in the CLI installation guide.

   Note

   If the club command isn’t found after installation, add ~/.local/bin to your PATH — the installer prints the exact line for your shell.

2. Login to your server

   club login localhost:8080

   club login accepts a bare host. localhost, 127.0.0.1, and 0.0.0.0 default to http://; everything else defaults to https://. A full URL like http://localhost:8080 is accepted too — both forms map to the same credential.

   By default this opens your browser and runs an OAuth 2.0 Authorization Code flow with PKCE. Approve the request in the browser and the CLI receives a scoped personal access token automatically.

   Note

   If you prefer a non-browser flow (for example, on a headless machine), use club login localhost:8080 --no-browser to fall back to a terminal email/password prompt, or pass an existing token with --key club_pat_....

3. Configure dart pub to use your server

   club setup

   This runs dart pub token add http://localhost:8080 behind the scenes, registering your credentials with the Dart SDK’s native token store. (club login already does this automatically; club setup is useful for switching to --env-var mode in CI.)

Publish a test package

1. Create a simple Dart package

   mkdir -p /tmp/hello_club && cd /tmp/hello_club

   Create pubspec.yaml:

   name: hello_club
   version: 1.0.0
   description: A test package for club.
   publish_to: http://localhost:8080
   
   environment:
     sdk: ^3.0.0

   Create lib/hello_club.dart:

   /// A friendly greeting from club.
   String greet(String name) => 'Hello, $name! Welcome to club.';

2. Publish the package

   dart pub publish --force

   Note

   The --force flag skips the confirmation prompt. Remove it if you want to review the package contents before publishing.

3. Verify on the web UI

   Open http://localhost:8080 in your browser. You should see hello_club listed on the packages page. Click it to see the full package detail page with metadata, the README, and installation instructions.

Use it in another project

1. Create a new Dart project

   mkdir -p /tmp/my_app && cd /tmp/my_app
   dart create -t console .

2. Add the private package as a dependency

   Edit pubspec.yaml and add:

   dependencies:
     hello_club:
       hosted: http://localhost:8080
       version: ^1.0.0

3. Fetch the dependency

   dart pub get

4. Use the package

   Edit bin/my_app.dart:

   import 'package:hello_club/hello_club.dart';
   
   void main() {
     print(greet('Developer'));
   }

   Run it:

   dart run

   Output:

   Hello, Developer! Welcome to club.

What’s next

You now have a working private Dart package repository. Here is what to do next:

• Installation guide — explore all installation options in detail
• First Package guide — learn the full publishing workflow with troubleshooting tips
• Docker deployment — set up a production deployment with persistent volumes and health checks
• TLS / HTTPS — required for production; dart pub will not send auth tokens over plain HTTP to non-localhost URLs
• Reverse proxy — put club behind Caddy or nginx for TLS termination