# Charon

> [!WARNING]
> This repository has been archived in favour of [hackclub/charon](https://github.com/hackclub/charon).

Charon is an API for inviting new users to a Slack workspace from various websites. It aims to provide a centralised system to manage invites.

## Usage

Please see the [docs](docs/README.md) for a detailed guide on how to implement Charon into your program

## Running locally

### Prerequesites

- Python (3.13 or later)
- uv
- A Slack workspace where you have permissions to install apps
- Tunneling tool (for local development)

## Setting up the Slack App

1. Go to [https://api.slack.com/apps](https://api.slack.com/apps) and click "Create New App".
2. Choose "From an app manifest" and select your workspace.
3. Copy and paste the manifest in `manifest.yml`, replacing `YOUR_URL` with your URL (we'll set this up later):
4. Review and create the app.
5. In the "Basic Information" section, note down the `App Id`, `Client Id`, `Client Secret`, `Signing Secret` .
6. Go to "OAuth & Permissions" and install the app to your workspace. Note down the "Bot User OAuth Token".

## Setting up the Project

1. Clone the repository:

   ```
   git clone https://github.com/transcental/charon.git
   cd charon
   ```

2. Install dependencies:

   ```
   uv sync
   source .venv/bin/activate # for bash/zsh
   source .venv/bin/activate.fish # for fish
   source .venv/bin/activate.csh # for csh
   source .venv/bin/activate.ps1 # for powershell
   ```

3. Copy the `.env.sample` file to `.env`:

   ```
   cp .env.sample .env
   ```

4. Edit the `.env` file and fill in the values:

   ```
   PORT=3000
   ENVIRONMENT="development"
   
   SLACK_BOT_TOKEN="bot-token"
   SLACK_SIGNING_SECRET="signing-secret"
   SLACK_APP_TOKEN="app-token" # This is optional - recommended to use socket mode in dev because it allows you to run the app locally without needing to tunnel. Not recommended for production.

   SLACK_HEARTBEAT_CHANNEL="channel-id"
   ```

   Replace the values with your actual parameters.


## Running the Application

1. Start your tunneling tool and expose the local server. (Not needed in socket mode with `SLACK_APP_TOKEN` set)

   Note the HTTPS URL you get.

2. Update your Slack app's request URLs:

   - Go to your Slack app's settings.
   - In "Event Subscriptions" and "Interactivity & Shortcuts", update the request URL to your HTTPS URL followed by `/slack/events`.
   - In "OAuth & Permissions", update `Redirect URLs` to your HTTPS URL followed by `/slack/oauth_redirect`.

3. Start the application:
   ```
   app
   ```

Your Slack app should now be running and connected to your Slack workspace!

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Migrations

If you make changes to the database schema, please create a migration file using:

```
alembic revision --autogenerate -m "Your migration message"
```

Then apply the migration with:

```
alembic upgrade head
```

## License

This project is licensed under the MIT License.