Docs: First time setup guides/quickstart

[bndw]

Is your feature request related to a problem? Please describe. I experienced a bit of friction on my deployment of Athens. I think there's room for improvement in documentation around typical setups and quickstart guides.

Describe the solution you'd like A quickstart guide for typical configurations. For example, configuring Athens with access to private Github repos, an S3 backend, under a docker deployment.

I specifically had a hard time tracking down configuration for private Github repositories. It went roughly as follows:

• Deployed v0.6.0, the latest release at the time
• Noticed 500 errors for private repositories when pointing GOPROXY at athens
• Searched the docs for "Github" but found nothing
• Searched the config file and found ATHENS_GITHUB_TOKEN
• Redeployed with a Github token, but still saw 500's
• Searched issues on the repo and found #1390
• Added ATHENS_GONOSUM_PATTERNS and redeployed

If this configuration is common, it might be nice to add a quickstart. I'd be happy to contribute.

[volker-raschek]

You're absolutely right, the documentary is terrible. I'm also looking in vain for information on configuring athens in a docker container via env variables.

[schafer14]

@bndw Excellent point, I think there is definitely an opportunity for improvement in the documentation around using private repositories. It is a little bit tricky because you have so many configuration combinations with the storage backends and the deployment type. It's like a choose your own adventure book. If you want to contribute to the docs that would be awesome! Sing out if you need any help at all.

@volker-raschek @arschles this is a really interesting comment to me. The lack of examples using Docker was a bit of a blind spot for me at least. Would it be helpful to write a documentation page with all the configuration options using Docker as a target?

[bndw]

Documentation can always be improved and IMHO this project is documented quite well. I think we're really just missing a higher-level doc to tie it all together for folks that are unfamiliar with the code base (once you get into the code, configs, etc, the details are available).

I'll work on a brief "quickstart" for the Docker, S3, Github setup that I'm running. I'm not sure where that should live in the existing documentation, but we can cross that bridge once I have a rough draft.

[schafer14]

@bndw Just wanted to make sure you know about these docs on writing docs https://docs.gomods.io/contributing/new/docs/. If you add your page underneath the introduction section that might be a good place to start and it can always be moved around later.

[arschles]

Sorry for the delay on response @bndw, @schafer14 and @volker-raschek! I was busy in Kubernetes land.

It sounds like there are two documents being discussed in this thread that would be helpful:

1. A quickstart for running in docker
2. More complete documentation for setting up storage, regardless of the target deployment platform

What do you all think? Also, for (2) above, could we make the storage docs more complete, instead of adding a brand new doc?

Let me know what (if anything) you'd like to contribute, and I'll fill in the gaps.

[arschles]

Also @bndw

I'll work on a brief "quickstart" for the Docker, S3, Github setup that I'm running

Let me know if/when you have something up in a PR (I couldn't find anything right now) and I'll help you find a good place for it 😄

[arschles]

You're absolutely right, the documentary is terrible. I'm also looking in vain for information on configuring athens in a docker container via env variables.

@volker-raschek I apologize that there are gaps in the documentation and that it makes you feel like the documentation is terrible. But, in the future can you also tell us some ideas for solving that problem?

For example, I think we would all benefit from hearing what specific environment variables and/or functionality is not documented? If there is some configuration that Athens is just missing, we can also add it into the codebase as well.

[bndw]

@arschles Planning to get something together in the coming days (also been lost in Kubernetes land 😅)

[volker-raschek]

Hello @arschles , first, I have looked for a feature to import self signed certificates. But I don't find a documented environment variable where I can store my self signed certificate neither a path inside the container image to store multiple self singed certificates over a volume which will be imported automatically at startup #1407. Currently I added the certificate over a new container image layer, but I think it's not be the right way.

There is only one reason why I use the Athens Proxy. I am instructed to cache every third library whose source code is publicly accessible and used in my company's projects and, at best, to make it available in a version control system. There is a danger that projects whose source code is public will be deleted or moved by users and will no longer be accessible in case of problems or other incidents. Thus, the source code of each project and its imported libraries must be kept available, so we would also be in the Feature Request #1424

Volker

[arschles]

@arschles Planning to get something together in the coming days (also been lost in Kubernetes land 😅)

@bndw no problem, just let us know when you're ready. We'll be here!

[arschles]

@volker-raschek thanks for laying out the specific things that you'd like improved. That was also really helpful for me to see your use case. I am going to comment separately in #1407 and #1424 right now, so that we can talk separately about each of those features and their documentation

[arschles]

@bndw are you still interested in writing some quickstart docs? Absolutely no pressure if not. I've been writing some in various places and just want to check in to make sure I don't step on your toes. Let me know 😄

[bndw]

👋 @arschles apologies for dropping the ball on the docs, go ahead without me!

[arschles]

@bndw not a problem! We'll probably tackle this in pieces, so feel free to jump back in if you ever feel like it 😄 .

[ChanceNCounter]

A weird thing on GitHub, but I think this issue is worthy of a bump, considering that its last activity was more than a year and a half ago, and I've just had the same experience over an evening and a morning.

So far, I've gotten to the point where I think the proxy should be redirecting certain requests to my local Gitea server, but instead it's checking its own storage and returning a 404. Obviously I don't want to troubleshoot that in this issue =P but that's where, in my particular case, the onboarding guides led me. I might be best served by starting from scratch. Fortunately, I'm working with Docker, so the "start from scratch" part is painless.