Skip to content

Latest commit

 

History

History
174 lines (146 loc) · 7.16 KB

CONTRIBUTING.md

File metadata and controls

174 lines (146 loc) · 7.16 KB
Raw

Contributing to Thetawave

Building and Running Tests

cargo test --workspace --all-features

Running the game locally

cargo run --release --features storage

Building the game with arcade functionality.

cargo build --release features storage --features arcade

Build and run the game for wasm.

Run

./build_wasm.sh

Then serve the out/ directory with some HTTP server.

For example

python3 -m http.server -d out/

Assets

We choose to store most images and audio (10Mb-1Gb) in AWS S3, rather than in git for the following reasons:

  • Git is good for determining text-based diffs and has reasonable merge strategies for text, but is not so useful for binary files like audio and images.
  • Time consuming git clone runs are annoying.
  • We may segregate "free" vs "premium" assets.

Some day we may try git annex, git LFS, or some more dedicated service that offers peer-review and s3-like operations of a distributed, versioned filesystem.

To contribute to the assets, do the following.

  1. Create an AWS account.

  2. Create an IAM User on your AWS account. This is distinct from your account's root user, and will only have permissions to contribute to Thetawave. Let's call this IAM user mythetawavedev. While slightly more complex than 1 user account/username+password pair, keeping deliberate and minimal permissions is a standard infosec and AWS IAM best practice.

  3. Send a repo maintainer your IAM User ARN. It will look something like arn:aws:iam::121767489999:user/mythetawavedev. The maintainer will allow you to use an AWS IAM Role that gives short term access to the assets.

  4. Using your root account (or one with privileges to manipulate IAM permissions), give your thetawave-specific IAM user permission to access our IAM role. Create and attach the following policy to your (nonroot) user.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRole"
      ],
      "Resource": [
        "arn:aws:iam::656454124102:role/ThetawaveDeveloperRole"
      ]
    }
  ]
}

    See AWS docs for more instructions.

  5. (Optional) For web browser/console/interactive access, log in as your IAM user account (not the root account) and see the ThetawaveDeveloperRole IAM role login. For example, in the assets-thetawave bucket console one can manually upload assets. This is useful for making sure permissions are set up properly, but is unnecessary for day-to-day operations.

  6. To download all of the assets from a local development environment using the aws-cli, I recommend putting long term access keys in an ~/.aws/credentials file like the following

    [thetawavedev]
aws_access_key_id = <MY_ACCESS_KEY>
aws_secret_access_key = <MY_SECRET_KEY>
region = us-east-2

    and manually creating an ~/.aws/config` file like

    [profile thetawavedev-p]
role_arn = arn:aws:iam::656454124102:role/ThetawaveDeveloperRole
source_profile = thetawavedev
role_session_name = <A_NAME_FOR_YOUR_SESSION>

    On Windows, the aws cli initially looks for these files at C:\Users\USERNAME\.aws\config and C:\Users\USERNAME\.aws\credentials.

    Once the credentials are stored locally, run ./asset_manager.py download free_assets or ./asset_manger.py --profile <YOUR_AWS_PROFILE_NAME> download premium_assets to invoke the AWS CLI. Or look at that script to figure out how to invoke the AWS CLI yourself.

    If you instead want to store these credentials outside of the standard ~/.aws directory, for example in a relative .aws directory, you may prefix commands with environment variables like

    AWS_SHARED_CREDENTIALS_FILE=path/to/credentials AWS_CONFIG_FILE=path/to/config \
     ./asset_manager.py --profile YOUR_PROFILE_NAME download

    AWS has more docs about configuring credentials. The aws-cli also has documentation in aws help config-vars.

  7. (Optional) If you are using another open source tool for interacting with S3, such as rclone, MinIO client, you may need to use --s3-profile or do something like the following.

export AWS_SESSION_TOKEN=$(aws sts assume-role --profile thetawavedev --output text \
    --role-arn arn:aws:iam::656454124102:role/ThetawaveDeveloperRole \
    --role-session-name vpsession --query="Credentials.SessionToken" )

<<<<<<< HEAD

Extra Nuglets

To delete just the premium assets from your local assets directory, run the following from the repo root.

aws --profile <YOUR_AWS_PROFILE_NAME> s3 ls --recursive s3://assets-thetawave/premium_assets/ \
    | awk '{print $4}' | sed 's/^premium_//' \ # Map into our "overlayed free-premium directory structure"
    | xargs rm -f

Accessing Assets in CI

As of 2023, the recommended way for automated tools like Github to access AWS S3 (for our game assets) is to use OIDC by allowing Github actions to assume an AWS IAM role with permissions to read the bucket. AWS and Github both maintain documentation describing how to do this.

One of the repo maintainers owns an AWS IAM role with the "Trust relationships" defined as follows.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::012345678910:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                },
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:thetawave/thetawave:*"
                }
            }
        }
    ]
}