gomods / athens

A Go module datastore and proxy
https://docs.gomods.io
MIT License
4.43k stars 499 forks source link

Docs: First time setup guides/quickstart #1406

Open bndw opened 5 years ago

bndw commented 5 years ago

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:

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

volker-raschek commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

volker-raschek commented 5 years ago

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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

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

arschles commented 4 years ago

@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 commented 2 years ago

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.