diff --git a/docs/docs/Advanced/sdk.md b/docs/docs/Advanced/sdk.md index 4a0d1ee87..1da065ac2 100644 --- a/docs/docs/Advanced/sdk.md +++ b/docs/docs/Advanced/sdk.md @@ -6,7 +6,7 @@ You can use BaGetter's [`BaGetter.Protocol`](https://www.nuget.org/packages/BaGe Install the [`BaGetter.Protocol`](https://www.nuget.org/packages/BaGetter.Protocol) package: -``` +```shell dotnet add package BaGetter.Protocol ``` diff --git a/docs/docs/Import/local-feeds.md b/docs/docs/Import/local-feeds.md index b427949b0..eb2420795 100644 --- a/docs/docs/Import/local-feeds.md +++ b/docs/docs/Import/local-feeds.md @@ -12,20 +12,20 @@ Please refer to the [BaGetter vs local feeds](../vs/local-feeds.md) page for rea Make sure that you've installed [nuget.exe](https://www.nuget.org/downloads). In PowerShell, run: -```ps1 +```powershell $source = "C:\path\to\local\feed" $destination = "http://localhost:5000/v3/index.json" ``` If you've [configured BaGetter to require an API Key](https://bagetter.com/docs/configuration/#requiring-an-api-key), set it using [the `setapikey` command](https://docs.microsoft.com/en-us/nuget/reference/cli-reference/cli-ref-setapikey): -```ps1 +```powershell & nuget.exe setapikey "MY-API-KEY" -Source $destination ``` Now run the following PowerShell script: -```ps1 +```powershell $packages = nuget list -AllVersions -Source $source $packages | % { diff --git a/docs/docs/Import/nugetorg.md b/docs/docs/Import/nugetorg.md index 89d2cbde2..a32627183 100644 --- a/docs/docs/Import/nugetorg.md +++ b/docs/docs/Import/nugetorg.md @@ -21,13 +21,13 @@ You can import package downloads from nuget.org: 1. Navigate to `.\BaGetter\src\BaGetter` 2. Run: -``` +```shell dotnet run -- import-downloads ``` ## Importing all nuget.org packages -* TODO Check-in code -* Explain scaling -* Rebuild indexes at end -* Importing downloads from nuget.org +- TODO Check-in code +- Explain scaling +- Rebuild indexes at end +- Importing downloads from nuget.org diff --git a/docs/docs/Import/nugetserver.md b/docs/docs/Import/nugetserver.md index 1f2276328..1ad9e303a 100644 --- a/docs/docs/Import/nugetserver.md +++ b/docs/docs/Import/nugetserver.md @@ -12,20 +12,20 @@ Please refer to the [BaGetter vs NuGet.Server](../vs/nugetserver.md) page for re Make sure that you've installed [nuget.exe](https://www.nuget.org/downloads). In PowerShell, run: -```ps1 +```powershell $source = "" $destination = "" ``` If you've [configured BaGetter to require an API Key](https://bagetter.com/docs/configuration/#requiring-an-api-key), set it using [the `setapikey` command](https://docs.microsoft.com/en-us/nuget/reference/cli-reference/cli-ref-setapikey): -```ps1 +```powershell & nuget.exe setapikey "MY-API-KEY" -Source $destination ``` Now run the following PowerShell script: -```ps1 +```powershell if (!(Test-Path "Web.config")) { throw "Please run this script in the same directory as NuGet.Server's Web.config file" } diff --git a/docs/docs/Index.md b/docs/docs/Index.md index 66fb45e45..c0bee1312 100644 --- a/docs/docs/Index.md +++ b/docs/docs/Index.md @@ -12,7 +12,6 @@ export const CenterImg = ({children, color}) => ( BaGetter (pronounced "ba getter") is a lightweight NuGet and symbol server. It is [open source](https://github.com/bagetter/BaGetter), cross-platform, and cloud ready! - @@ -21,12 +20,12 @@ BaGetter (pronounced "ba getter") is a lightweight NuGet and symbol server. It i You can run BaGetter on your preferred platform: -* [On your computer](Installation/local.md) -* [Docker](Installation/docker.md) -* [Azure](Installation/azure.md) -* [AWS](Installation/aws.md) -* [Google Cloud](Installation/gcp.md) -* [Alibaba Cloud (Aliyun)](Installation/aliyun.md) +- [On your computer](Installation/local.md) +- [Docker](Installation/docker.md) +- [Azure](Installation/azure.md) +- [AWS](Installation/aws.md) +- [Google Cloud](Installation/gcp.md) +- [Alibaba Cloud (Aliyun)](Installation/aliyun.md) ## BaGetter SDK diff --git a/docs/docs/Installation/aws.md b/docs/docs/Installation/aws.md index b97150208..3b5b4707f 100644 --- a/docs/docs/Installation/aws.md +++ b/docs/docs/Installation/aws.md @@ -95,13 +95,13 @@ To use [SQL Server](https://aws.amazon.com/rds/sqlserver), update the `appsettin Publish your first package with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json package.1.0.0.nupkg ``` Publish your first [symbol package](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json symbol.package.1.0.0.snupkg ``` diff --git a/docs/docs/Installation/azure.md b/docs/docs/Installation/azure.md index 66edcac69..050b1a15e 100644 --- a/docs/docs/Installation/azure.md +++ b/docs/docs/Installation/azure.md @@ -10,9 +10,9 @@ Use Azure to scale BaGetter. You can store metadata on [Azure SQL Database](http ## TODO -* App Service -* Table Storage -* High availability setup +- App Service +- Table Storage +- High availability setup ## Configure BaGetter @@ -45,7 +45,6 @@ Update the `appsettings.json` file: "Storage": { "Type": "AzureBlobStorage", - "AccountName": "my-account", "AccessKey": "abcd1234", "Container": "my-container" @@ -63,7 +62,6 @@ Alternatively, you can use a full Azure Storage connection string: "Storage": { "Type": "AzureBlobStorage", - "ConnectionString": "AccountName=my-account;AccountKey=abcd1234;...", "Container": "my-container" }, @@ -94,13 +92,13 @@ Update the `appsettings.json` file: Publish your first package with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json package.1.0.0.nupkg ``` Publish your first [symbol package](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json symbol.package.1.0.0.snupkg ``` @@ -118,8 +116,8 @@ You can restore packages by using the following package source: Some helpful guides: -* [Visual Studio](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio#package-sources) -* [NuGet.config](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) +- [Visual Studio](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio#package-sources) +- [NuGet.config](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) ## Symbol server diff --git a/docs/docs/Installation/docker.md b/docs/docs/Installation/docker.md index 09a742b2b..e592249ed 100644 --- a/docs/docs/Installation/docker.md +++ b/docs/docs/Installation/docker.md @@ -4,7 +4,7 @@ Create a file named `bagetter.env` to store BaGetter's configurations: -``` +```shell # The following config is the API Key used to publish packages. # You should change this to a secret value to secure your server. ApiKey=NUGET-SERVER-API-KEY @@ -32,7 +32,7 @@ If this step is omitted the default mode (unconfigured) will be Sqlite with the 1. Create a folder named `bagetter-data` in the same directory as the `bagetter.env` file. This will be used by BaGetter to persist its state. 2. Pull BaGetter's latest [docker image](hhttps://hub.docker.com/r/bagetter/bagetter): -``` +```shell docker pull bagetter/bagetter ``` @@ -40,13 +40,13 @@ You can now run BaGetter... - ...with optional `.env` file: -``` +```shell docker run --rm --name nuget-server -p 5000:8080 --env-file bagetter.env -v "$(pwd)/bagetter-data:/data" bagetter/bagetter:latest ``` - ...or without: -``` +```shell docker run --rm --name nuget-server -p 5000:8080 -v "$(pwd)/bagetter-data:/data" bagetter/bagetter:latest ``` @@ -54,13 +54,13 @@ docker run --rm --name nuget-server -p 5000:8080 -v "$(pwd)/bagetter-data:/data" Publish your first package with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json -k NUGET-SERVER-API-KEY package.1.0.0.nupkg ``` Publish your first [symbol package](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json -k NUGET-SERVER-API-KEY symbol.package.1.0.0.snupkg ``` diff --git a/docs/docs/Installation/gcp.md b/docs/docs/Installation/gcp.md index e2bddc413..a2021d831 100644 --- a/docs/docs/Installation/gcp.md +++ b/docs/docs/Installation/gcp.md @@ -44,12 +44,12 @@ Configure BaGetter to use Google Cloud Storage by updating the `appsettings.json ## Google Cloud SQL -* Follow the instructions in [Using Cloud SQL](https://cloud.google.com/appengine/docs/flexible/dotnet/using-cloud-sql) to create a 2nd Gen MySQL 5.7 Google Cloud SQL instance. The default options should work well. -* Create a database named `bagetter`. This can be done through the Google Cloud Console. Use `utf8mb4` as the Character set. -* Follow [Configuring SSL/TLS](https://cloud.google.com/sql/docs/mysql/configure-ssl-instance#new-client) to create a client certificate. Download the three files it creates. -* Convert the PEM to a PFX by running `openssl pkcs12 -inkey client-key.pem -in client-cert.pem -export -out client.pfx` - * One way to obtain OpenSSL on Windows is to install [Git Bash](https://gitforwindows.org/). -* Configure BaGetter to use Google Cloud SQL by updating the [`appsettings.json`](https://github.com/bagetter/BaGetter/blob/master/src/BaGetter/appsettings.json) file: +- Follow the instructions in [Using Cloud SQL](https://cloud.google.com/appengine/docs/flexible/dotnet/using-cloud-sql) to create a 2nd Gen MySQL 5.7 Google Cloud SQL instance. The default options should work well. +- Create a database named `bagetter`. This can be done through the Google Cloud Console. Use `utf8mb4` as the Character set. +- Follow [Configuring SSL/TLS](https://cloud.google.com/sql/docs/mysql/configure-ssl-instance#new-client) to create a client certificate. Download the three files it creates. +- Convert the PEM to a PFX by running `openssl pkcs12 -inkey client-key.pem -in client-cert.pem -export -out client.pfx` + - One way to obtain OpenSSL on Windows is to install [Git Bash](https://gitforwindows.org/). +- Configure BaGetter to use Google Cloud SQL by updating the [`appsettings.json`](https://github.com/bagetter/BaGetter/blob/master/src/BaGetter/appsettings.json) file: ```json { @@ -62,7 +62,7 @@ Configure BaGetter to use Google Cloud Storage by updating the `appsettings.json } ``` -* Create the tables by running `dotnet ef database update --context MySqlContext --project src\BaGetter` +- Create the tables by running `dotnet ef database update --context MySqlContext --project src\BaGetter` ## Google AppEngine @@ -72,12 +72,12 @@ for a tutorial on how to create a new AppEngine project. Create a `app.yaml` file to publish the Docker container built by the Dockerfile in this repo. In the template below, make the following replacements: -* `PROJECT` - your GCP project, as returned by `gcloud config get-value project` -* `REGION` -- the GCP region your Google Cloud SQL database is in, e.g., `us-central1` or `us-west2` -* `DBINSTANCE` -- the name of your Google Cloud SQL database instance -* `DBNAME` -- the name of the BaGetter database on that instance (e.g., `bagetter` in the instructions above) -* `PASSWORD` -- the password for the database root user -* `BUCKETNAME` -- the name of the Google Cloud Storage Bucket configured above +- `PROJECT` - your GCP project, as returned by `gcloud config get-value project` +- `REGION` -- the GCP region your Google Cloud SQL database is in, e.g., `us-central1` or `us-west2` +- `DBINSTANCE` -- the name of your Google Cloud SQL database instance +- `DBNAME` -- the name of the BaGetter database on that instance (e.g., `bagetter` in the instructions above) +- `PASSWORD` -- the password for the database root user +- `BUCKETNAME` -- the name of the Google Cloud Storage Bucket configured above ```yaml runtime: custom diff --git a/docs/docs/Installation/iis-proxy.md b/docs/docs/Installation/iis-proxy.md index dfc3f9462..ac6550d19 100644 --- a/docs/docs/Installation/iis-proxy.md +++ b/docs/docs/Installation/iis-proxy.md @@ -5,15 +5,13 @@ With a few extra steps you can run BaGetter behind a Windows IIS proxy. This has ## IIS setup 1. Install the [.NET Core Runtime](https://dotnet.microsoft.com/download) on the web server. -1. Copy the BaGetter directory over to your hosting area such as `C:\Inetpub\wwwroot\BaGetter` -1. Using IIS Manager, create a new Application Pool: - +2. Copy the BaGetter directory over to your hosting area such as `C:\Inetpub\wwwroot\BaGetter` +3. Using IIS Manager, create a new Application Pool: - Name = `BaGetterAppPool` (can be whatever you want) - .NET CLR version = No Managed Code - Managed Pipeline Mode = Integrated - Start application pool immediately = checked - -1. Using IIS Manager, create a new web site: +4. Using IIS Manager, create a new web site: - Choose your site name and physical path - Choose `BaGetterAppPool` as the application pool - In the Binding area, enter the default BaGetter port of 5000 @@ -47,7 +45,6 @@ Ensure that the configuration's storage `Path` has the appropriate forward slash Note that you will need to adjust folder permissions if the `Path` is created outside of the BaGetter top-level directory. See the [BaGettert Folder Permissions](#bagetter-folder-permissions). - ## IIS server options -Settings such as the maximum package size can be configured for IIS in the appsettings.json file - see [IIS Server Options](../configuration.md#iis-server-options). \ No newline at end of file +Settings such as the maximum package size can be configured for IIS in the appsettings.json file - see [IIS Server Options](../configuration.md#iis-server-options). diff --git a/docs/docs/Installation/local.md b/docs/docs/Installation/local.md index aa893bbc8..e3ce221b2 100644 --- a/docs/docs/Installation/local.md +++ b/docs/docs/Installation/local.md @@ -3,9 +3,9 @@ ## Run BaGetter 1. Install the [.NET Core SDK](https://www.microsoft.com/net/download) -1. Download and extract [BaGetter's latest release](https://github.com/bagetter/BaGetter/releases) -1. Start the service with `dotnet BaGetter.dll` -1. Browse `http://localhost:5000/` in your browser +2. Download and extract [BaGetter's latest release](https://github.com/bagetter/BaGetter/releases) +3. Start the service with `dotnet BaGetter.dll` +4. Browse `http://localhost:5000/` in your browser ## Configure BaGetter @@ -15,13 +15,13 @@ You can modify BaGetter's configurations by editing the `appsettings.json` file. Publish your first package with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json package.1.0.0.nupkg ``` Publish your first [symbol package](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) with: -``` +```shell dotnet nuget push -s http://localhost:5000/v3/index.json symbol.package.1.0.0.snupkg ``` diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md index c295a3fdd..0a7bb2a87 100644 --- a/docs/docs/configuration.md +++ b/docs/docs/configuration.md @@ -16,7 +16,7 @@ To do so, you can insert the desired API key in the `ApiKey` field. Users will now have to provide the API key to push packages: -```c# +```shell dotnet nuget push -s http://localhost:5000/v3/index.json -k NUGET-SERVER-API-KEY package.1.0.0.nupkg ``` @@ -26,7 +26,7 @@ Read-through caching lets you index packages from an upstream source. You can us caching to: 1. Speed up your builds if restores from [nuget.org](https://nuget.org) are slow -1. Enable package restores in offline scenarios +2. Enable package restores in offline scenarios The following `Mirror` setting configures BaGetter to index packages from [nuget.org](https://nuget.org): @@ -96,7 +96,6 @@ Private feeds are not supported at this time! See [this pull request](https://gi BaGetter supports multiple database engines for storing package information: - - MySQL: `MySql` - SQLite: `Sqlite` - SQL Server: `SqlServer` @@ -162,7 +161,7 @@ If not specified, the `MaxRequestBodySize` in BaGetter defaults to 250MB (262144 Mostly useful when running containerised (e.g. using Docker, Podman, Kubernetes, etc), the application will look for files named in the same pattern as environment variables under `/run/secrets`. -``` +```shell /run/secrets/Database__ConnectionString ``` diff --git a/docs/docs/vs/liget.md b/docs/docs/vs/liget.md index 0e0d7ffb2..3ed4bb3a7 100644 --- a/docs/docs/vs/liget.md +++ b/docs/docs/vs/liget.md @@ -8,12 +8,12 @@ This page is a work in progress! [LiGet](https://github.com/ai-traders/liget) is a NuGet server created with a linux-first approach. -* LiGet - * Strong support for Paket - * Only supports NuGet's v2 APIs (missing verified packages, signed packages, etc...) - * Stores all packages' metadata using a single JSON file -* BaGetter - * Supports NuGet's v3 APIs - * Stores packages' metadata in a database - * Capable of ingesting all packages on nuget.org - * Can run on Azure \ No newline at end of file +- LiGet + - Strong support for Paket + - Only supports NuGet's v2 APIs (missing verified packages, signed packages, etc...) + - Stores all packages' metadata using a single JSON file +- BaGetter + - Supports NuGet's v3 APIs + - Stores packages' metadata in a database + - Capable of ingesting all packages on nuget.org + - Can run on Azure diff --git a/docs/docs/vs/local-feeds.md b/docs/docs/vs/local-feeds.md index af47f9c81..812df3d99 100644 --- a/docs/docs/vs/local-feeds.md +++ b/docs/docs/vs/local-feeds.md @@ -9,11 +9,11 @@ This page is a work in progress! [Local feeds](https://docs.microsoft.com/en-us/nuget/hosting-packages/local-feeds), also known as "folder feeds", let you use a folder as a NuGet package source. You can access these packages using a network share. -# BaGetter vs local feeds +## BaGetter vs local feeds Local feeds are very simple and are lack features like: 1. Search functionality -1. A user interface to browse your packages -1. Authentication for package uploads -1. Cloud storage for large feeds +2. A user interface to browse your packages +3. Authentication for package uploads +4. Cloud storage for large feeds diff --git a/docs/docs/vs/nugetorg.md b/docs/docs/vs/nugetorg.md index 6fcf0f42f..881f67859 100644 --- a/docs/docs/vs/nugetorg.md +++ b/docs/docs/vs/nugetorg.md @@ -13,32 +13,32 @@ The Gallery is battle-tested and proven to scale well. You can find a guide on h your own Gallery instance on [the Gallery's wiki](https://github.com/NuGet/NuGetGallery/wiki/Hosting-nuget.org's-v3-services). You can find the Gallery's code on GitHub: -* [NuGet/NuGetGallery](https://github.com/NuGet/NuGetGallery) - the [nuget.org](https://nuget.org) +- [NuGet/NuGetGallery](https://github.com/NuGet/NuGetGallery) - the [nuget.org](https://nuget.org) website and v2 APIs -* [NuGet/NuGet.Jobs](https://github.com/NuGet/NuGet.Jobs/) - the Gallery's jobs for things like validation and package statistics. -* [NuGet/NuGet.Services.Metadata](https://github.com/NuGet/NuGet.Services.Metadata/) - NuGet's v3 implementation -* [NuGet/ServerCommon](https://github.com/NuGet/ServerCommon) - common libraries used across NuGet's services +- [NuGet/NuGet.Jobs](https://github.com/NuGet/NuGet.Jobs/) - the Gallery's jobs for things like validation and package statistics. +- [NuGet/NuGet.Services.Metadata](https://github.com/NuGet/NuGet.Services.Metadata/) - NuGet's v3 implementation +- [NuGet/ServerCommon](https://github.com/NuGet/ServerCommon) - common libraries used across NuGet's services As you can tell, nuget.org is a complex beast. Hosting your own instance of the Gallery is not for the faint of heart. -# BaGetter vs nuget.org +## BaGetter vs nuget.org TODO. See [this issue](https://github.com/loic-sharma/BaGet/issues/71) for a deep-dive. -* BaGetter only competes with [NuGet/NuGet.Services.Metadata](https://github.com/NuGet/NuGet.Services.Metadata/) -* nuget.org's v3 implementation is static - * Runs only on Windows - * Highly tied to Azure - * Scales reads to near infinity - * Doesn't scale well for writes - * Static JSON files are hosted on Azure Blob Storage - * Served by a Content Delivery Network - * Files are updated by `feed2catalog`, `catalog2registration`, `catalog2dnx`, and `catalog2lucene` jobs -* BaGetter's v3 implementation is dynamic - * Cross-platform implementation - * Requests are served by a service that queries a database - * Simpler architecture, which makes it easier to deploy and run small feeds - * Easier to scale for writes - * Harder to scale for reads - * Easier to add new features - * Harder to make as reliable \ No newline at end of file +- BaGetter only competes with [NuGet/NuGet.Services.Metadata](https://github.com/NuGet/NuGet.Services.Metadata/) +- nuget.org's v3 implementation is static + - Runs only on Windows + - Highly tied to Azure + - Scales reads to near infinity + - Doesn't scale well for writes + - Static JSON files are hosted on Azure Blob Storage + - Served by a Content Delivery Network + - Files are updated by `feed2catalog`, `catalog2registration`, `catalog2dnx`, and `catalog2lucene` jobs +- BaGetter's v3 implementation is dynamic + - Cross-platform implementation + - Requests are served by a service that queries a database + - Simpler architecture, which makes it easier to deploy and run small feeds + - Easier to scale for writes + - Harder to scale for reads + - Easier to add new features + - Harder to make as reliable diff --git a/docs/docs/vs/nugetserver.md b/docs/docs/vs/nugetserver.md index d7faa101d..136eb0ef4 100644 --- a/docs/docs/vs/nugetserver.md +++ b/docs/docs/vs/nugetserver.md @@ -8,17 +8,17 @@ This page is a work in progress! [NuGet.Server](https://github.com/NuGet/NuGet.Server) is a lightweight standalone NuGet server. It is strongly recommended that you upgrade to BaGetter if you use NuGet.Server. Feel free to open [GitHub issues](https://github.com/bagetter/BaGetter/issues) if you need help migrating. -* NuGet.Server - * Only runs on Windows - * Supports NuGet v2 APIs (missing verified packages, signed packages, etc...) - * Doesn't support NuGet's v3 APIs - * Does not scale well - * Not well documented - * Not well maintained -* BaGetter - * Cross-platform - * Supports NuGet v3 APIs +- NuGet.Server + - Only runs on Windows + - Supports NuGet v2 APIs (missing verified packages, signed packages, etc...) + - Doesn't support NuGet's v3 APIs + - Does not scale well + - Not well documented + - Not well maintained +- BaGetter + - Cross-platform + - Supports NuGet v3 APIs ## Migration Guide -You can use the [NuGet.Server migration](../Import/nugetserver.md) guide to import your NuGet.Server packages into BaGetter. \ No newline at end of file +You can use the [NuGet.Server migration](../Import/nugetserver.md) guide to import your NuGet.Server packages into BaGetter. diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index d55a89419..744ffff13 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -113,6 +113,9 @@ const config: Config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, + //builtInLanguages: https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/generate-prism-languages/index.ts#L9 + //supportedLanguages: https://prismjs.com/#supported-languages + additionalLanguages: ['csharp', 'json', 'powershell', 'javascript', 'bash'], }, } satisfies Preset.ThemeConfig, };