feature(scripts): Add a buildscript for a local superchain docker

[jusdino]

I don't know if this is useful for you but, in case it is, here's what I did to make local development and building a little more convenient:

Related to #20041, I found that the jsii/superchain docker image ran into issues accessing the mounted-in filesystem because of mismatch between local file ownership and the container user/group. This local image buildscript gets past that by setting up a user inside a local version of the superchain image that has the needed uid and gid, and is a member of the docker group. With this script I was able to build all of aws-cdk-lib like so:

$ git clone https://github.com/{your-account}/aws-cdk.git
$ cd aws-cdk
$ ./scripts/build-local-superchain.sh
$ docker run --rm --net=host -ti -v "$PWD:$PWD" -v '/var/run/docker.sock:/var/run/docker.sock' -w "$PWD" superchain-local
  $ yarn install
  $ cd packages/@aws-cdk/aws-cdk-lib
  $ ../../scripts/buildup  && ../../scripts/foreach.sh --up yarn run package

This local-image-build approach has the benefit of enjoying the benefits of using the entire toolchain from superchain, while still being able to produce artifacts that are owned with the right local permissions.

Note: The included Dockerfile starts FROM: jsii/superchain:1-buster-slim-node14, though I understand from @RomainMuller that it should be updated to just :1-buser-slim as soon as that image is updated to use node14.

---

All Submissions:

• Have you followed the guidelines in our Contributing guide?

Adding new Unconventional Dependencies:

• This PR adds new unconventional dependencies following the process described here

New Features

• Have you added the new feature to an integration test?
  • Did you use yarn integ to deploy the infrastructure and generate the snapshot (i.e. yarn integ without --dry-run)?

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[gitpod-io]

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildProject89A8053A-LhjRyN9kxr8o
• Commit ID: 1159caf
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[mrgrain]

Hi @jusdino apologies for the long delay. Could you confirm what OS you are experience the permissions issues with?

I suspect you're on Linux, which has well-documented issues with file permissions in shared volumes. Usually this is the other way around though, you wouldn't be able to access files created in the container.

[jusdino]

Hi @jusdino apologies for the long delay. Could you confirm what OS you are experience the permissions issues with?

I suspect you're on Linux, which has well-documented issues with file permissions in shared volumes. Usually this is the other way around though, you wouldn't be able to access files created in the container.

Yessir. I'm running Amazon Linux 2 :)

For the permissions issues being the other-way-round usually, I suspect that would be when the docker container is root, so they can do whatever they like to the files that are mounted in. When the superchain image switched to a normal user (and not one that necessarily exists on the docker host), it became subject to the other side of file access issues.

[mrgrain]

@jusdino Apologies for the delay. Can you confirm that it's the packing part
that it's not working for you on Amazon Linux 2 and that this PR is attempting to solve?

The jsii/superchain is maintained in a different repo, so I'm not convinced adding the local build here is the right thing to do. Furthermore I'm investigating other solutions. Have you tried anything else that didn't end up working?

[jusdino]

@mrgrain , anything that involved writing any file to the project would fail, so yarn install, yarn build, anything will fail, if you are running on a linux filesystem which prohibits writing to local directories for anybody who isn't the owner of those directories. From the OS's perspective, the superchain container's user is just a user who has no write permissions to the filesystem and so it will deny such access. I tried a variety of options to various degrees of success (though, I was mostly focused on the linked issue problems rather than local file system problems). The key things I tried were:

1. Passing a docker run option that ignores the image's user and instead runs it as root. This would successfully build anything we liked, but from outside the container, now I had a whole bunch of files peppered across the repo that were owned by root, and so my real user did not have permission to mess with them, which is highly obnoxious in any workflow I could conjure up.

2. Altering the local repo permissions to recursively allow non-owner-users to write to them. This also worked ok, though was more subject to errors, since any local installs or other operations that created a directory afterword would leave a landmine in the project that would break the superchain tooling, when it tried to write there. Then, when I ran anything inside superchain, I wind up with a bunch of files written to my local filesystem that are owned by a user my OS doesn't recognize, and so I run into similar problems as if they were owned by root.

This is why it seemed my best option was to rig the superchain image up so that it can actually run with a user that looks just like my local user, thus avoiding all the headaches around file-owner issues.

[mrgrain]

Thanks again for your response @jusdino I'm trying to correctly understand your use case. Is your workflow to checkout the code on the host, then run jsii:superchain and do most of the development work inside the container?

From our perspective jsii/superchain is currently supported for automated builds and managed cloud environments [1]. In both cases, all filesystem interactions (including git) are transparently handled by a user inside the container and thus not an issue. Before we are embarking on a new scenario, I'd like to understand it better and make sure it helps a decent amount of our users.

One thing that's not great at the moment are VSCode Devcontainers. I think this it would benefit a large number of people. There also appears to be a built-in support for the permissions issue. Is that a solution you'd be interested in?

[1] GitPod, and to a lesser degree GitHub Codespaces

[jusdino]

Yeah that all makes a lot of sense to me.

So my use case mostly boils down to this:
I'm totally good with a normal local development workflow for making changes in TypeScript, but occasionally, I want to be able to verify that my local TS modifications produce artifacts in the other supported languages with the changes I expect. To do that, I need some means of actually building those libraries, and superchain seems to be the preferred way to do that.

[mrgrain]

Okay, I finally had time to look a bit further into this and it seems like there are a few more issues with the current documentation around packaging. I think we will be much better served improving the docs, than explicitly supporting every use case.

I'll be closing this PR in the next few days and will try to follow up with documentation improvements soon. It seems like there are good workarounds for you and I recommend you keep the superchain Dockerfile with your uid/gid around. No promises, but maybe the source repo for superchain would be open to a PR that adds ARGs for uid/gid.

[jusdino]

Makes sense! Thanks for digging!